Video for Linux Two

March 15, 2000 - 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.

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

I am working on a 2.3.x version, but it is not ready yet.


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-12-23
Standard Image Formats [ http:/ ] 1999-03-26
Data Services Interface (VBI) Specification [ http:/ ] 1999-12-20
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. videodev20000113.tgz [ http:/ ] 2000-01-13 (23KB) -new API
Previous V4L2 sources videodev19991202.tgz [ http:/ ] 1999-12-02 (23KB) -new API
Previous V4L2 sources videodev19990921.tgz [ http:/ ] 1999-09-21 (22KB)
Sample applications (xcaptest, vidpanel, vcat, vctrl). Includes a Makefile apps20000217.tgz [ http:/ ] 2000-02-17 (10KB) -new API
Previous sample applications apps19990605.tgz [ http:/ ] 1999-06-05 (10KB)
Sample drivers (v4l2cap.c, v4l2out.c) v4l2samp19990921.tgz [ http:/ ] 1999-09-21 (32KB) -new API
Previous sample drivers v4l2samp19990805.tgz [ http:/ ] 1999-08-05 (32KB)
V4L2 API Changes Log [ http:/ ]

Download videodev??????.tgz.
# cd /usr/src/linux
# tar zxvf videodev??????.tgz
Configure Video for Linux as a module, and rebuild kernel if necessary.
# make modules; make modules_install

See the drivers/char/v4l2readme.txt file for details.

When you unpack videodev*.tgz in /usr/src/linux, it will overwrite include/linux/videodev.h and drivers/char/videodev.c. You may want to keep backup copies of these files in case you decide to go back to v4l.

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 device driver specifications have settled down, but there might be a few minor changes.

Copyright 2000 http:/