Part I - Video for Linux API

This part describes the Video for Linux API version 2 (V4L2 API) specification.

Revision 4.5

Table of Contents

Revision History

revision:

4.10 / 2016-07-15 (rr)

Introduce HSV formats.

revision:

4.5 / 2015-10-29 (rr)

Extend VIDIOC_G_EXT_CTRLS;. Replace ctrl_class with a new union with ctrl_class and which. Which is used to select the current value of the control or the default value.

revision:

4.4 / 2015-05-26 (ap)

Renamed V4L2_TUNER_ADC to V4L2_TUNER_SDR. Added V4L2_CID_RF_TUNER_RF_GAIN control. Added transmitter support for Software Defined Radio (SDR) Interface.

revision:

4.1 / 2015-02-13 (mcc)

Fix documentation for media controller device nodes and add support for DVB device nodes. Add support for Tuner sub-device.

revision:

3.19 / 2014-12-05 (hv)

Rewrote Colorspace chapter, added new enum v4l2_ycbcr_encoding and enum v4l2_quantization fields to struct v4l2_pix_format, struct v4l2_pix_format_mplane and struct v4l2_mbus_framefmt.

revision:

3.17 / 2014-08-04 (lp, hv)

Extended struct v4l2_pix_format. Added format flags. Added compound control types and VIDIOC_QUERY_EXT_CTRL.

revision:

3.15 / 2014-02-03 (hv, ap)

Update several sections of "Common API Elements": "Opening and Closing Devices" "Querying Capabilities", "Application Priority", "Video Inputs and Outputs", "Audio Inputs and Outputs" "Tuners and Modulators", "Video Standards" and "Digital Video (DV) Timings". Added SDR API.

revision:

3.14 / 2013-11-25 (rr)

Set width and height as unsigned on v4l2_rect.

revision:

3.11 / 2013-05-26 (hv)

Remove obsolete VIDIOC_DBG_G_CHIP_IDENT ioctl.

revision:

3.10 / 2013-03-25 (hv)

Remove obsolete and unused DV_PRESET ioctls: VIDIOC_G_DV_PRESET, VIDIOC_S_DV_PRESET, VIDIOC_QUERY_DV_PRESET and VIDIOC_ENUM_DV_PRESET. Remove the related v4l2_input/output capability flags V4L2_IN_CAP_PRESETS and V4L2_OUT_CAP_PRESETS. Added VIDIOC_DBG_G_CHIP_INFO.

revision:

3.9 / 2012-12-03 (sa, sn)

Added timestamp types to v4l2_buffer. Added V4L2_EVENT_CTRL_CH_RANGE control event changes flag.

revision:

3.6 / 2012-07-02 (hv)

Added VIDIOC_ENUM_FREQ_BANDS.

revision:

3.5 / 2012-05-07 (sa, sn, hv)

Added V4L2_CTRL_TYPE_INTEGER_MENU and V4L2 subdev selections API. Improved the description of V4L2_CID_COLORFX control, added V4L2_CID_COLORFX_CBCR control. Added camera controls V4L2_CID_AUTO_EXPOSURE_BIAS, V4L2_CID_AUTO_N_PRESET_WHITE_BALANCE, V4L2_CID_IMAGE_STABILIZATION, V4L2_CID_ISO_SENSITIVITY, V4L2_CID_ISO_SENSITIVITY_AUTO, V4L2_CID_EXPOSURE_METERING, V4L2_CID_SCENE_MODE, V4L2_CID_3A_LOCK, V4L2_CID_AUTO_FOCUS_START, V4L2_CID_AUTO_FOCUS_STOP, V4L2_CID_AUTO_FOCUS_STATUS and V4L2_CID_AUTO_FOCUS_RANGE. Added VIDIOC_ENUM_DV_TIMINGS, VIDIOC_QUERY_DV_TIMINGS and VIDIOC_DV_TIMINGS_CAP.

revision:

3.4 / 2012-01-25 (sn)

Added JPEG compression control class.

revision:

3.3 / 2012-01-11 (hv)

Added device_caps field to struct v4l2_capabilities.

revision:

3.2 / 2011-08-26 (hv)

Added V4L2_CTRL_FLAG_VOLATILE.

revision:

3.1 / 2011-06-27 (mcc, po, hv)

Documented that VIDIOC_QUERYCAP now returns a per-subsystem version instead of a per-driver one. Standardize an error code for invalid ioctl. Added V4L2_CTRL_TYPE_BITMASK.

revision:

2.6.39 / 2011-03-01 (mcc, po)

Removed VIDIOC_*_OLD from videodev2.h header and update it to reflect latest changes. Added the multi-planar API.

revision:

2.6.37 / 2010-08-06 (hv)

Removed obsolete vtx (videotext) API.

revision:

2.6.33 / 2009-12-03 (mk)

Added documentation for the Digital Video timings API.

revision:

2.6.32 / 2009-08-31 (mcc)

Now, revisions will match the kernel version where the V4L2 API changes will be used by the Linux Kernel. Also added Remote Controller chapter.

revision:

0.29 / 2009-08-26 (ev)

Added documentation for string controls and for FM Transmitter controls.

revision:

0.28 / 2009-08-26 (gl)

Added V4L2_CID_BAND_STOP_FILTER documentation.

revision:

0.27 / 2009-08-15 (mcc)

Added libv4l and Remote Controller documentation; added v4l2grab and keytable application examples.

revision:

0.26 / 2009-07-23 (hv)

Finalized the RDS capture API. Added modulator and RDS encoder capabilities. Added support for string controls.

revision:

0.25 / 2009-01-18 (hv)

Added pixel formats VYUY, NV16 and NV61, and changed the debug ioctls VIDIOC_DBG_G/S_REGISTER and VIDIOC_DBG_G_CHIP_IDENT. Added camera controls V4L2_CID_ZOOM_ABSOLUTE, V4L2_CID_ZOOM_RELATIVE, V4L2_CID_ZOOM_CONTINUOUS and V4L2_CID_PRIVACY.

revision:

0.24 / 2008-03-04 (mhs)

Added pixel formats Y16 and SBGGR16, new controls and a camera controls class. Removed VIDIOC_G/S_MPEGCOMP.

revision:

0.23 / 2007-08-30 (mhs)

Fixed a typo in VIDIOC_DBG_G/S_REGISTER. Clarified the byte order of packed pixel formats.

revision:

0.22 / 2007-08-29 (mhs)

Added the Video Output Overlay interface, new MPEG controls, V4L2_FIELD_INTERLACED_TB and V4L2_FIELD_INTERLACED_BT, VIDIOC_DBG_G/S_REGISTER, VIDIOC_(TRY_)ENCODER_CMD, VIDIOC_G_CHIP_IDENT, VIDIOC_G_ENC_INDEX, new pixel formats. Clarifications in the cropping chapter, about RGB pixel formats, the mmap(), poll(), select(), read() and write() functions. Typographical fixes.

revision:

0.21 / 2006-12-19 (mhs)

Fixed a link in the VIDIOC_G_EXT_CTRLS section.

revision:

0.20 / 2006-11-24 (mhs)

Clarified the purpose of the audioset field in struct v4l2_input and v4l2_output.

revision:

0.19 / 2006-10-19 (mhs)

Documented V4L2_PIX_FMT_RGB444.

revision:

0.18 / 2006-10-18 (mhs)

Added the description of extended controls by Hans Verkuil. Linked V4L2_PIX_FMT_MPEG to V4L2_CID_MPEG_STREAM_TYPE.

revision:

0.17 / 2006-10-12 (mhs)

Corrected V4L2_PIX_FMT_HM12 description.

revision:

0.16 / 2006-10-08 (mhs)

VIDIOC_ENUM_FRAMESIZES and VIDIOC_ENUM_FRAMEINTERVALS are now part of the API.

revision:

0.15 / 2006-09-23 (mhs)

Cleaned up the bibliography, added BT.653 and BT.1119. capture.c/start_capturing() for user pointer I/O did not initialize the buffer index. Documented the V4L MPEG and MJPEG VID_TYPEs and V4L2_PIX_FMT_SBGGR8. Updated the list of reserved pixel formats. See the history chapter for API changes.

revision:

0.14 / 2006-09-14 (mr)

Added VIDIOC_ENUM_FRAMESIZES and VIDIOC_ENUM_FRAMEINTERVALS proposal for frame format enumeration of digital devices.

revision:

0.13 / 2006-04-07 (mhs)

Corrected the description of struct v4l2_window clips. New V4L2_STD_ and V4L2_TUNER_MODE_LANG1_LANG2 defines.

revision:

0.12 / 2006-02-03 (mhs)

Corrected the description of struct v4l2_captureparm and v4l2_outputparm.

revision:

0.11 / 2006-01-27 (mhs)

Improved the description of struct v4l2_tuner.

revision:

0.10 / 2006-01-10 (mhs)

VIDIOC_G_INPUT and VIDIOC_S_PARM clarifications.

revision:

0.9 / 2005-11-27 (mhs)

Improved the 525 line numbering diagram. Hans Verkuil and I rewrote the sliced VBI section. He also contributed a VIDIOC_LOG_STATUS page. Fixed VIDIOC_S_STD call in the video standard selection example. Various updates.

revision:

0.8 / 2004-10-04 (mhs)

Somehow a piece of junk slipped into the capture example, removed.

revision:

0.7 / 2004-09-19 (mhs)

Fixed video standard selection, control enumeration, downscaling and aspect example. Added read and user pointer i/o to video capture example.

revision:

0.6 / 2004-08-01 (mhs)

v4l2_buffer changes, added video capture example, various corrections.

revision:

0.5 / 2003-11-05 (mhs)

Pixel format erratum.

revision:

0.4 / 2003-09-17 (mhs)

Corrected source and Makefile to generate a PDF. SGML fixes. Added latest API changes. Closed gaps in the history chapter.

revision:

0.3 / 2003-02-05 (mhs)

Another draft, more corrections.

revision:

0.2 / 2003-01-15 (mhs)

Second draft, with corrections pointed out by Gerd Knorr.

revision:

0.1 / 2002-12-01 (mhs)

First draft, based on documentation by Bill Dirks and discussions on the V4L mailing list.