Video for Linux Two

September 21, 1999 - Bill Dirks ( )

I am creating an overhauled Video for Linux API made to be more flexible and extensible, and to support more kinds of devices. The existing API will to keep shipping with Linux to maintain compatibility. I am calling the new API Video for Linux Two (or "V4L2" for short). A user wishing to use the new API installs the Video for Linux Two files, which replace the corresponding files for the original API.

V4L2 is a thorough overhaul of the API with respect to Video for Linux, and not backward compatible with the original API, so drivers already written for Video for Linux will have to be ported to work with V4L2.

Applications should also be ported to make the best use of V4L2, but there is a backward compatibility layer built in to the V4L2 high level driver that translates the old ioctl commands, so many applications written for the original API will still work with V4L2 drivers.

On this page you will find general information about V4L2, and V4L2 resources, including documentation and source code, and links to drivers and applications that have been written for or ported to V4L2.

Companion Library (libv4l2 [ http:/ ] )

The existing V4L2 specifications are for the device driver interface. We are now working on a user-mode function library to act as a layer between application code and the device drivers, to make writing applications to V4L2 easier. When it is ready, all V4L2 functionality will be available through the library, so it will not be necessary for applications to make any driver calls directly.
May 30: Michael has now made the library available. Get it from the libv4l2 page [ http:/ ]. Not complete yet, but usable. Includes some simple sample applications. Contributions welcome.

Devices, Drivers, Libraries and Applications

At the People & Projects [ http:/ ] page. This is a list of people who are contributing to V4L2 or doing V4L2-related work, and the projects they are working on. These include specifications, drivers, libraries, and applications.

V4L2 requires Linux kernel 2.2.x (or a late 2.1.x kernel).


These are the kernel device driver API specifications. The Driver Writer's Guide documents the V4L2 kernel-mode API functions, and provides additional information regarding how to write V4L2 drivers.

Video for Linux Two Documentation
Video for Linux Two Devices [ http:/ ] 1999-09-12
Video Capture API Specification [ http:/ ] 1999-09-14
Codec API Specification [ http:/ ] 1999-09-13
Effects API Specification [ http:/ ] 1999-09-19
Video Output Device API Specification [ http:/ ] 1999-09-19
Driver Writer's Guide [ http:/ ] 1999-09-20
Standard Image Formats [ http:/ ] 1999-03-26
Data Services Interface (VBI) Specification [ http:/ ] 1999-01-14
All API documents in a gzip'ed tar file: v4l2api.tgz [ http:/ ]

Source Code

For instructions on installing V4L2 see the readme file in the V4L2 source archive. You will need to configure your kernel to include Video for Linux as a module, but disable all the v4l drivers since they will not compile after the original v4l header file has been replaced with the new header file.

The v4l2samp.tgz file includes a sample device drivers which use no hardware, so you can start writing or porting applications to V4L2 even if you don't have V4L2-supported hardware yet. So far video capture and video output sample drivers are included. More information is in the readme file included in the archive.

There is now a sample capture program, xcaptest.c, which exercises the capture functions of a V4L2 driver. And a video control panel program, vidpanel.c, that exercises the brightness, contrast, etc. controls on a V4L2 device. These work with the sample capture driver. These are in the apps.tgz file. The vcat and vctrl programs are for use from the command line or a shell script, and are for capturing frames, and setting device parameters.

Notice: On Sep 21, 1999 I introduced some changes into the API [ http:/ ] that are not backward compatible. The 19990921 versions of these files and later incorporate these changes. If the driver for your hardware has not been updated, you will need earlier versions of these files. Those of you who are maintaining drivers or applications, see the above link for a list of what changes were made. Feel free to email me if you have questions or need assistance.

Video for Linux Two Source Code
V4L2 source code: videodev.c & videodev.h files. Unpack in /usr/src/linux. videodev19990921.tgz [ http:/ ] 1999-09-21 (23KB)
Previous V4L2 sources videodev19990905.tgz [ http:/ ] 1999-09-05 (23KB)
Previous V4L2 sources videodev19990830.tgz [ http:/ ] 1999-08-30 (22KB)
Sample applications (xcaptest, vidpanel, vcat, vctrl). Includes a Makefile apps19990921.tgz [ http:/ ] 1999-09-21 (10KB)
Previous sample applications apps19990605.tgz [ http:/ ] 1999-06-05 (10KB)
Sample drivers (v4l2cap.c, v4l2out.c) v4l2samp19990921.tgz [ http:/ ] 1999-09-21 (32KB)
Previous sample drivers v4l2samp19990805.tgz [ http:/ ] 1999-08-05 (32KB)
V4L2 API Changes Log [ http:/ ]

When you unpack videodev*.tgz in /usr/src/linux, it will overwrite include/linux/videodev.h and drivers/char/videodev.c.

Videodev.c and videodev.h are covered by the GPL. The sample code including v4l2cap, xcaptest, and vidpanel are public domain and have no copying or derived-work restrictions of any kind.

Help With V4L2 and Contributing

If you would like to contribute to the V4L2 project, or have any questions about the API or software supporting it, send me an email. Of course, I will be happy to answer any questions about V4L2 or provide advice or assistance with writing V4L2 drivers or applications.

If you have suggestions or patches for V4L2 source code send them to me at, or the V4L mail list at . To subscribe to the list, send email to with the subject subscribe.

If sending patches, I would ask that you please send patches as (gzip'ed) attachments because it has been my experience that 'patch' almost always rejects patches emailed in the body of a letter due to either tabs converted to spaces or wrapping of long lines.

When emailing to me, it is convenient for me if you include "v4l2" in the subject of the message.

Commercial Applications and Deployment

The user function library is still under construction. The device driver specifications have settled down, but there might be a few minor changes as the library API is designed. Application projects can be begun using the driver API directly for now, and porting to the function library later if desired.

Copyright 1999