1 .. -*- coding: utf-8; mode: rst -*-
13 The control mechanism as originally designed was meant to be used for
14 user settings (brightness, saturation, etc). However, it turned out to
15 be a very useful model for implementing more complicated driver APIs
16 where each driver implements only a subset of a larger API.
18 The MPEG encoding API was the driving force behind designing and
19 implementing this extended control mechanism: the MPEG standard is quite
20 large and the currently supported hardware MPEG encoders each only
21 implement a subset of this standard. Further more, many parameters
22 relating to how the video is encoded into an MPEG stream are specific to
23 the MPEG encoding chip since the MPEG standard only defines the format
24 of the resulting MPEG stream, not how the video is actually encoded into
27 Unfortunately, the original control API lacked some features needed for
28 these new uses and so it was extended into the (not terribly originally
29 named) extended control API.
31 Even though the MPEG encoding API was the first effort to use the
32 Extended Control API, nowadays there are also other classes of Extended
33 Controls, such as Camera Controls and FM Transmitter Controls. The
34 Extended Controls API as well as all Extended Controls classes are
35 described in the following text.
38 The Extended Control API
39 ========================
41 Three new ioctls are available:
42 :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`,
43 :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` and
44 :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`. These ioctls act
45 on arrays of controls (as opposed to the
46 :ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` and
47 :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls that act on a single
48 control). This is needed since it is often required to atomically change
49 several controls at once.
51 Each of the new ioctls expects a pointer to a struct
52 :c:type:`v4l2_ext_controls`. This structure
53 contains a pointer to the control array, a count of the number of
54 controls in that array and a control class. Control classes are used to
55 group similar controls into a single class. For example, control class
56 ``V4L2_CTRL_CLASS_USER`` contains all user controls (i. e. all controls
57 that can also be set using the old :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>`
58 ioctl). Control class ``V4L2_CTRL_CLASS_MPEG`` contains all controls
59 relating to MPEG encoding, etc.
61 All controls in the control array must belong to the specified control
62 class. An error is returned if this is not the case.
64 It is also possible to use an empty control array (``count`` == 0) to check
65 whether the specified control class is supported.
67 The control array is a struct
68 :c:type:`v4l2_ext_control` array. The
69 struct :c:type:`v4l2_ext_control` is very similar to
70 struct :c:type:`v4l2_control`, except for the fact that
71 it also allows for 64-bit values and pointers to be passed.
73 Since the struct :c:type:`v4l2_ext_control` supports
74 pointers it is now also possible to have controls with compound types
75 such as N-dimensional arrays and/or structures. You need to specify the
76 ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` when enumerating controls to actually
77 be able to see such compound controls. In other words, these controls
78 with compound types should only be used programmatically.
80 Since such compound controls need to expose more information about
81 themselves than is possible with
82 :ref:`VIDIOC_QUERYCTRL` the
83 :ref:`VIDIOC_QUERY_EXT_CTRL <VIDIOC_QUERYCTRL>` ioctl was added. In
84 particular, this ioctl gives the dimensions of the N-dimensional array
85 if this control consists of more than one element.
89 #. It is important to realize that due to the flexibility of controls it is
90 necessary to check whether the control you want to set actually is
91 supported in the driver and what the valid range of values is. So use
92 the :ref:`VIDIOC_QUERYCTRL` (or :ref:`VIDIOC_QUERY_EXT_CTRL
93 <VIDIOC_QUERYCTRL>`) and :ref:`VIDIOC_QUERYMENU <VIDIOC_QUERYCTRL>`
96 #. It is possible that some of the menu indices in a control of
97 type ``V4L2_CTRL_TYPE_MENU`` may not be supported (``VIDIOC_QUERYMENU``
98 will return an error). A good example is the list of supported MPEG
99 audio bitrates. Some drivers only support one or two bitrates, others
100 support a wider range.
102 All controls use machine endianness.
105 Enumerating Extended Controls
106 =============================
108 The recommended way to enumerate over the extended controls is by using
109 :ref:`VIDIOC_QUERYCTRL` in combination with the
110 ``V4L2_CTRL_FLAG_NEXT_CTRL`` flag:
115 struct v4l2_queryctrl qctrl;
117 qctrl.id = V4L2_CTRL_FLAG_NEXT_CTRL;
118 while (0 == ioctl (fd, VIDIOC_QUERYCTRL, &qctrl)) {
120 qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL;
123 The initial control ID is set to 0 ORed with the
124 ``V4L2_CTRL_FLAG_NEXT_CTRL`` flag. The ``VIDIOC_QUERYCTRL`` ioctl will
125 return the first control with a higher ID than the specified one. When
126 no such controls are found an error is returned.
128 If you want to get all controls within a specific control class, then
129 you can set the initial ``qctrl.id`` value to the control class and add
130 an extra check to break out of the loop when a control of another
131 control class is found:
136 qctrl.id = V4L2_CTRL_CLASS_MPEG | V4L2_CTRL_FLAG_NEXT_CTRL;
137 while (0 == ioctl(fd, VIDIOC_QUERYCTRL, &qctrl)) {
138 if (V4L2_CTRL_ID2CLASS(qctrl.id) != V4L2_CTRL_CLASS_MPEG)
141 qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL;
144 The 32-bit ``qctrl.id`` value is subdivided into three bit ranges: the
145 top 4 bits are reserved for flags (e. g. ``V4L2_CTRL_FLAG_NEXT_CTRL``)
146 and are not actually part of the ID. The remaining 28 bits form the
147 control ID, of which the most significant 12 bits define the control
148 class and the least significant 16 bits identify the control within the
149 control class. It is guaranteed that these last 16 bits are always
150 non-zero for controls. The range of 0x1000 and up are reserved for
151 driver-specific controls. The macro ``V4L2_CTRL_ID2CLASS(id)`` returns
152 the control class ID based on a control ID.
154 If the driver does not support extended controls, then
155 ``VIDIOC_QUERYCTRL`` will fail when used in combination with
156 ``V4L2_CTRL_FLAG_NEXT_CTRL``. In that case the old method of enumerating
157 control should be used (see :ref:`enum_all_controls`). But if it is
158 supported, then it is guaranteed to enumerate over all controls,
159 including driver-private controls.
162 Creating Control Panels
163 =======================
165 It is possible to create control panels for a graphical user interface
166 where the user can select the various controls. Basically you will have
167 to iterate over all controls using the method described above. Each
168 control class starts with a control of type
169 ``V4L2_CTRL_TYPE_CTRL_CLASS``. ``VIDIOC_QUERYCTRL`` will return the name
170 of this control class which can be used as the title of a tab page
171 within a control panel.
173 The flags field of struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` also
174 contains hints on the behavior of the control. See the
175 :ref:`VIDIOC_QUERYCTRL` documentation for more
181 Codec Control Reference
182 =======================
184 Below all controls within the Codec control class are described. First
185 the generic controls, then controls specific for certain hardware.
189 These controls are applicable to all codecs and not just MPEG. The
190 defines are prefixed with V4L2_CID_MPEG/V4L2_MPEG as the controls
191 were originally made for MPEG codecs and later extended to cover all
195 Generic Codec Controls
196 ----------------------
204 ``V4L2_CID_MPEG_CLASS (class)``
205 The Codec class descriptor. Calling
206 :ref:`VIDIOC_QUERYCTRL` for this control will
207 return a description of this control class. This description can be
208 used as the caption of a Tab page in a GUI, for example.
210 .. _v4l2-mpeg-stream-type:
212 ``V4L2_CID_MPEG_STREAM_TYPE``
215 enum v4l2_mpeg_stream_type -
216 The MPEG-1, -2 or -4 output stream type. One cannot assume anything
217 here. Each hardware MPEG encoder tends to support different subsets
218 of the available MPEG stream types. This control is specific to
219 multiplexed MPEG streams. The currently defined stream types are:
230 - ``V4L2_MPEG_STREAM_TYPE_MPEG2_PS``
232 - MPEG-2 program stream
236 - ``V4L2_MPEG_STREAM_TYPE_MPEG2_TS``
238 - MPEG-2 transport stream
242 - ``V4L2_MPEG_STREAM_TYPE_MPEG1_SS``
244 - MPEG-1 system stream
248 - ``V4L2_MPEG_STREAM_TYPE_MPEG2_DVD``
250 - MPEG-2 DVD-compatible stream
254 - ``V4L2_MPEG_STREAM_TYPE_MPEG1_VCD``
256 - MPEG-1 VCD-compatible stream
260 - ``V4L2_MPEG_STREAM_TYPE_MPEG2_SVCD``
262 - MPEG-2 SVCD-compatible stream
266 ``V4L2_CID_MPEG_STREAM_PID_PMT (integer)``
267 Program Map Table Packet ID for the MPEG transport stream (default
270 ``V4L2_CID_MPEG_STREAM_PID_AUDIO (integer)``
271 Audio Packet ID for the MPEG transport stream (default 256)
273 ``V4L2_CID_MPEG_STREAM_PID_VIDEO (integer)``
274 Video Packet ID for the MPEG transport stream (default 260)
276 ``V4L2_CID_MPEG_STREAM_PID_PCR (integer)``
277 Packet ID for the MPEG transport stream carrying PCR fields (default
280 ``V4L2_CID_MPEG_STREAM_PES_ID_AUDIO (integer)``
281 Audio ID for MPEG PES
283 ``V4L2_CID_MPEG_STREAM_PES_ID_VIDEO (integer)``
284 Video ID for MPEG PES
286 .. _v4l2-mpeg-stream-vbi-fmt:
288 ``V4L2_CID_MPEG_STREAM_VBI_FMT``
291 enum v4l2_mpeg_stream_vbi_fmt -
292 Some cards can embed VBI data (e. g. Closed Caption, Teletext) into
293 the MPEG stream. This control selects whether VBI data should be
294 embedded, and if so, what embedding method should be used. The list
295 of possible VBI formats depends on the driver. The currently defined
296 VBI format types are:
300 .. tabularcolumns:: |p{6 cm}|p{11.5cm}|
309 - ``V4L2_MPEG_STREAM_VBI_FMT_NONE``
311 - No VBI in the MPEG stream
315 - ``V4L2_MPEG_STREAM_VBI_FMT_IVTV``
317 - VBI in private packets, IVTV format (documented in the kernel
319 ``Documentation/video4linux/cx2341x/README.vbi``)
323 .. _v4l2-mpeg-audio-sampling-freq:
325 ``V4L2_CID_MPEG_AUDIO_SAMPLING_FREQ``
328 enum v4l2_mpeg_audio_sampling_freq -
329 MPEG Audio sampling frequency. Possible values are:
340 - ``V4L2_MPEG_AUDIO_SAMPLING_FREQ_44100``
346 - ``V4L2_MPEG_AUDIO_SAMPLING_FREQ_48000``
352 - ``V4L2_MPEG_AUDIO_SAMPLING_FREQ_32000``
358 .. _v4l2-mpeg-audio-encoding:
360 ``V4L2_CID_MPEG_AUDIO_ENCODING``
363 enum v4l2_mpeg_audio_encoding -
364 MPEG Audio encoding. This control is specific to multiplexed MPEG
365 streams. Possible values are:
376 - ``V4L2_MPEG_AUDIO_ENCODING_LAYER_1``
378 - MPEG-1/2 Layer I encoding
382 - ``V4L2_MPEG_AUDIO_ENCODING_LAYER_2``
384 - MPEG-1/2 Layer II encoding
388 - ``V4L2_MPEG_AUDIO_ENCODING_LAYER_3``
390 - MPEG-1/2 Layer III encoding
394 - ``V4L2_MPEG_AUDIO_ENCODING_AAC``
396 - MPEG-2/4 AAC (Advanced Audio Coding)
400 - ``V4L2_MPEG_AUDIO_ENCODING_AC3``
402 - AC-3 aka ATSC A/52 encoding
406 .. _v4l2-mpeg-audio-l1-bitrate:
408 ``V4L2_CID_MPEG_AUDIO_L1_BITRATE``
411 enum v4l2_mpeg_audio_l1_bitrate -
412 MPEG-1/2 Layer I bitrate. Possible values are:
423 - ``V4L2_MPEG_AUDIO_L1_BITRATE_32K``
429 - ``V4L2_MPEG_AUDIO_L1_BITRATE_64K``
435 - ``V4L2_MPEG_AUDIO_L1_BITRATE_96K``
441 - ``V4L2_MPEG_AUDIO_L1_BITRATE_128K``
447 - ``V4L2_MPEG_AUDIO_L1_BITRATE_160K``
453 - ``V4L2_MPEG_AUDIO_L1_BITRATE_192K``
459 - ``V4L2_MPEG_AUDIO_L1_BITRATE_224K``
465 - ``V4L2_MPEG_AUDIO_L1_BITRATE_256K``
471 - ``V4L2_MPEG_AUDIO_L1_BITRATE_288K``
477 - ``V4L2_MPEG_AUDIO_L1_BITRATE_320K``
483 - ``V4L2_MPEG_AUDIO_L1_BITRATE_352K``
489 - ``V4L2_MPEG_AUDIO_L1_BITRATE_384K``
495 - ``V4L2_MPEG_AUDIO_L1_BITRATE_416K``
501 - ``V4L2_MPEG_AUDIO_L1_BITRATE_448K``
507 .. _v4l2-mpeg-audio-l2-bitrate:
509 ``V4L2_CID_MPEG_AUDIO_L2_BITRATE``
512 enum v4l2_mpeg_audio_l2_bitrate -
513 MPEG-1/2 Layer II bitrate. Possible values are:
524 - ``V4L2_MPEG_AUDIO_L2_BITRATE_32K``
530 - ``V4L2_MPEG_AUDIO_L2_BITRATE_48K``
536 - ``V4L2_MPEG_AUDIO_L2_BITRATE_56K``
542 - ``V4L2_MPEG_AUDIO_L2_BITRATE_64K``
548 - ``V4L2_MPEG_AUDIO_L2_BITRATE_80K``
554 - ``V4L2_MPEG_AUDIO_L2_BITRATE_96K``
560 - ``V4L2_MPEG_AUDIO_L2_BITRATE_112K``
566 - ``V4L2_MPEG_AUDIO_L2_BITRATE_128K``
572 - ``V4L2_MPEG_AUDIO_L2_BITRATE_160K``
578 - ``V4L2_MPEG_AUDIO_L2_BITRATE_192K``
584 - ``V4L2_MPEG_AUDIO_L2_BITRATE_224K``
590 - ``V4L2_MPEG_AUDIO_L2_BITRATE_256K``
596 - ``V4L2_MPEG_AUDIO_L2_BITRATE_320K``
602 - ``V4L2_MPEG_AUDIO_L2_BITRATE_384K``
608 .. _v4l2-mpeg-audio-l3-bitrate:
610 ``V4L2_CID_MPEG_AUDIO_L3_BITRATE``
613 enum v4l2_mpeg_audio_l3_bitrate -
614 MPEG-1/2 Layer III bitrate. Possible values are:
625 - ``V4L2_MPEG_AUDIO_L3_BITRATE_32K``
631 - ``V4L2_MPEG_AUDIO_L3_BITRATE_40K``
637 - ``V4L2_MPEG_AUDIO_L3_BITRATE_48K``
643 - ``V4L2_MPEG_AUDIO_L3_BITRATE_56K``
649 - ``V4L2_MPEG_AUDIO_L3_BITRATE_64K``
655 - ``V4L2_MPEG_AUDIO_L3_BITRATE_80K``
661 - ``V4L2_MPEG_AUDIO_L3_BITRATE_96K``
667 - ``V4L2_MPEG_AUDIO_L3_BITRATE_112K``
673 - ``V4L2_MPEG_AUDIO_L3_BITRATE_128K``
679 - ``V4L2_MPEG_AUDIO_L3_BITRATE_160K``
685 - ``V4L2_MPEG_AUDIO_L3_BITRATE_192K``
691 - ``V4L2_MPEG_AUDIO_L3_BITRATE_224K``
697 - ``V4L2_MPEG_AUDIO_L3_BITRATE_256K``
703 - ``V4L2_MPEG_AUDIO_L3_BITRATE_320K``
709 ``V4L2_CID_MPEG_AUDIO_AAC_BITRATE (integer)``
710 AAC bitrate in bits per second.
712 .. _v4l2-mpeg-audio-ac3-bitrate:
714 ``V4L2_CID_MPEG_AUDIO_AC3_BITRATE``
717 enum v4l2_mpeg_audio_ac3_bitrate -
718 AC-3 bitrate. Possible values are:
729 - ``V4L2_MPEG_AUDIO_AC3_BITRATE_32K``
735 - ``V4L2_MPEG_AUDIO_AC3_BITRATE_40K``
741 - ``V4L2_MPEG_AUDIO_AC3_BITRATE_48K``
747 - ``V4L2_MPEG_AUDIO_AC3_BITRATE_56K``
753 - ``V4L2_MPEG_AUDIO_AC3_BITRATE_64K``
759 - ``V4L2_MPEG_AUDIO_AC3_BITRATE_80K``
765 - ``V4L2_MPEG_AUDIO_AC3_BITRATE_96K``
771 - ``V4L2_MPEG_AUDIO_AC3_BITRATE_112K``
777 - ``V4L2_MPEG_AUDIO_AC3_BITRATE_128K``
783 - ``V4L2_MPEG_AUDIO_AC3_BITRATE_160K``
789 - ``V4L2_MPEG_AUDIO_AC3_BITRATE_192K``
795 - ``V4L2_MPEG_AUDIO_AC3_BITRATE_224K``
801 - ``V4L2_MPEG_AUDIO_AC3_BITRATE_256K``
807 - ``V4L2_MPEG_AUDIO_AC3_BITRATE_320K``
813 - ``V4L2_MPEG_AUDIO_AC3_BITRATE_384K``
819 - ``V4L2_MPEG_AUDIO_AC3_BITRATE_448K``
825 - ``V4L2_MPEG_AUDIO_AC3_BITRATE_512K``
831 - ``V4L2_MPEG_AUDIO_AC3_BITRATE_576K``
837 - ``V4L2_MPEG_AUDIO_AC3_BITRATE_640K``
843 .. _v4l2-mpeg-audio-mode:
845 ``V4L2_CID_MPEG_AUDIO_MODE``
848 enum v4l2_mpeg_audio_mode -
849 MPEG Audio mode. Possible values are:
860 - ``V4L2_MPEG_AUDIO_MODE_STEREO``
866 - ``V4L2_MPEG_AUDIO_MODE_JOINT_STEREO``
872 - ``V4L2_MPEG_AUDIO_MODE_DUAL``
878 - ``V4L2_MPEG_AUDIO_MODE_MONO``
884 .. _v4l2-mpeg-audio-mode-extension:
886 ``V4L2_CID_MPEG_AUDIO_MODE_EXTENSION``
889 enum v4l2_mpeg_audio_mode_extension -
890 Joint Stereo audio mode extension. In Layer I and II they indicate
891 which subbands are in intensity stereo. All other subbands are coded
892 in stereo. Layer III is not (yet) supported. Possible values are:
903 - ``V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_4``
905 - Subbands 4-31 in intensity stereo
909 - ``V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_8``
911 - Subbands 8-31 in intensity stereo
915 - ``V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_12``
917 - Subbands 12-31 in intensity stereo
921 - ``V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_16``
923 - Subbands 16-31 in intensity stereo
927 .. _v4l2-mpeg-audio-emphasis:
929 ``V4L2_CID_MPEG_AUDIO_EMPHASIS``
932 enum v4l2_mpeg_audio_emphasis -
933 Audio Emphasis. Possible values are:
944 - ``V4L2_MPEG_AUDIO_EMPHASIS_NONE``
950 - ``V4L2_MPEG_AUDIO_EMPHASIS_50_DIV_15_uS``
952 - 50/15 microsecond emphasis
956 - ``V4L2_MPEG_AUDIO_EMPHASIS_CCITT_J17``
962 .. _v4l2-mpeg-audio-crc:
964 ``V4L2_CID_MPEG_AUDIO_CRC``
967 enum v4l2_mpeg_audio_crc -
968 CRC method. Possible values are:
979 - ``V4L2_MPEG_AUDIO_CRC_NONE``
985 - ``V4L2_MPEG_AUDIO_CRC_CRC16``
987 - 16 bit parity check
991 ``V4L2_CID_MPEG_AUDIO_MUTE (boolean)``
992 Mutes the audio when capturing. This is not done by muting audio
993 hardware, which can still produce a slight hiss, but in the encoder
994 itself, guaranteeing a fixed and reproducible audio bitstream. 0 =
997 .. _v4l2-mpeg-audio-dec-playback:
999 ``V4L2_CID_MPEG_AUDIO_DEC_PLAYBACK``
1002 enum v4l2_mpeg_audio_dec_playback -
1003 Determines how monolingual audio should be played back. Possible
1008 .. tabularcolumns:: |p{9.0cm}|p{8.5cm}|
1017 - ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_AUTO``
1019 - Automatically determines the best playback mode.
1023 - ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_STEREO``
1029 - ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_LEFT``
1031 - Left channel playback.
1035 - ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_RIGHT``
1037 - Right channel playback.
1041 - ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_MONO``
1047 - ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_SWAPPED_STEREO``
1049 - Stereo playback with swapped left and right channels.
1053 .. _v4l2-mpeg-audio-dec-multilingual-playback:
1055 ``V4L2_CID_MPEG_AUDIO_DEC_MULTILINGUAL_PLAYBACK``
1058 enum v4l2_mpeg_audio_dec_playback -
1059 Determines how multilingual audio should be played back.
1061 .. _v4l2-mpeg-video-encoding:
1063 ``V4L2_CID_MPEG_VIDEO_ENCODING``
1066 enum v4l2_mpeg_video_encoding -
1067 MPEG Video encoding method. This control is specific to multiplexed
1068 MPEG streams. Possible values are:
1079 - ``V4L2_MPEG_VIDEO_ENCODING_MPEG_1``
1081 - MPEG-1 Video encoding
1085 - ``V4L2_MPEG_VIDEO_ENCODING_MPEG_2``
1087 - MPEG-2 Video encoding
1091 - ``V4L2_MPEG_VIDEO_ENCODING_MPEG_4_AVC``
1093 - MPEG-4 AVC (H.264) Video encoding
1097 .. _v4l2-mpeg-video-aspect:
1099 ``V4L2_CID_MPEG_VIDEO_ASPECT``
1102 enum v4l2_mpeg_video_aspect -
1103 Video aspect. Possible values are:
1114 - ``V4L2_MPEG_VIDEO_ASPECT_1x1``
1118 - ``V4L2_MPEG_VIDEO_ASPECT_4x3``
1122 - ``V4L2_MPEG_VIDEO_ASPECT_16x9``
1126 - ``V4L2_MPEG_VIDEO_ASPECT_221x100``
1130 ``V4L2_CID_MPEG_VIDEO_B_FRAMES (integer)``
1131 Number of B-Frames (default 2)
1133 ``V4L2_CID_MPEG_VIDEO_GOP_SIZE (integer)``
1134 GOP size (default 12)
1136 ``V4L2_CID_MPEG_VIDEO_GOP_CLOSURE (boolean)``
1137 GOP closure (default 1)
1139 ``V4L2_CID_MPEG_VIDEO_PULLDOWN (boolean)``
1140 Enable 3:2 pulldown (default 0)
1142 .. _v4l2-mpeg-video-bitrate-mode:
1144 ``V4L2_CID_MPEG_VIDEO_BITRATE_MODE``
1147 enum v4l2_mpeg_video_bitrate_mode -
1148 Video bitrate mode. Possible values are:
1159 - ``V4L2_MPEG_VIDEO_BITRATE_MODE_VBR``
1165 - ``V4L2_MPEG_VIDEO_BITRATE_MODE_CBR``
1171 ``V4L2_CID_MPEG_VIDEO_BITRATE (integer)``
1172 Video bitrate in bits per second.
1174 ``V4L2_CID_MPEG_VIDEO_BITRATE_PEAK (integer)``
1175 Peak video bitrate in bits per second. Must be larger or equal to
1176 the average video bitrate. It is ignored if the video bitrate mode
1177 is set to constant bitrate.
1179 ``V4L2_CID_MPEG_VIDEO_TEMPORAL_DECIMATION (integer)``
1180 For every captured frame, skip this many subsequent frames (default
1183 ``V4L2_CID_MPEG_VIDEO_MUTE (boolean)``
1184 "Mutes" the video to a fixed color when capturing. This is useful
1185 for testing, to produce a fixed video bitstream. 0 = unmuted, 1 =
1188 ``V4L2_CID_MPEG_VIDEO_MUTE_YUV (integer)``
1189 Sets the "mute" color of the video. The supplied 32-bit integer is
1190 interpreted as follows (bit 0 = least significant bit):
1203 - V chrominance information
1209 - U chrominance information
1215 - Y luminance information
1225 .. _v4l2-mpeg-video-dec-pts:
1227 ``V4L2_CID_MPEG_VIDEO_DEC_PTS (integer64)``
1228 This read-only control returns the 33-bit video Presentation Time
1229 Stamp as defined in ITU T-REC-H.222.0 and ISO/IEC 13818-1 of the
1230 currently displayed frame. This is the same PTS as is used in
1231 :ref:`VIDIOC_DECODER_CMD`.
1233 .. _v4l2-mpeg-video-dec-frame:
1235 ``V4L2_CID_MPEG_VIDEO_DEC_FRAME (integer64)``
1236 This read-only control returns the frame counter of the frame that
1237 is currently displayed (decoded). This value is reset to 0 whenever
1238 the decoder is started.
1240 ``V4L2_CID_MPEG_VIDEO_DECODER_SLICE_INTERFACE (boolean)``
1241 If enabled the decoder expects to receive a single slice per buffer,
1242 otherwise the decoder expects a single frame in per buffer.
1243 Applicable to the decoder, all codecs.
1245 ``V4L2_CID_MPEG_VIDEO_H264_VUI_SAR_ENABLE (boolean)``
1246 Enable writing sample aspect ratio in the Video Usability
1247 Information. Applicable to the H264 encoder.
1249 .. _v4l2-mpeg-video-h264-vui-sar-idc:
1251 ``V4L2_CID_MPEG_VIDEO_H264_VUI_SAR_IDC``
1254 enum v4l2_mpeg_video_h264_vui_sar_idc -
1255 VUI sample aspect ratio indicator for H.264 encoding. The value is
1256 defined in the table E-1 in the standard. Applicable to the H264
1268 - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_UNSPECIFIED``
1274 - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_1x1``
1280 - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_12x11``
1286 - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_10x11``
1292 - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_16x11``
1298 - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_40x33``
1304 - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_24x11``
1310 - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_20x11``
1316 - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_32x11``
1322 - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_80x33``
1328 - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_18x11``
1334 - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_15x11``
1340 - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_64x33``
1346 - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_160x99``
1352 - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_4x3``
1358 - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_3x2``
1364 - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_2x1``
1370 - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_EXTENDED``
1376 ``V4L2_CID_MPEG_VIDEO_H264_VUI_EXT_SAR_WIDTH (integer)``
1377 Extended sample aspect ratio width for H.264 VUI encoding.
1378 Applicable to the H264 encoder.
1380 ``V4L2_CID_MPEG_VIDEO_H264_VUI_EXT_SAR_HEIGHT (integer)``
1381 Extended sample aspect ratio height for H.264 VUI encoding.
1382 Applicable to the H264 encoder.
1384 .. _v4l2-mpeg-video-h264-level:
1386 ``V4L2_CID_MPEG_VIDEO_H264_LEVEL``
1389 enum v4l2_mpeg_video_h264_level -
1390 The level information for the H264 video elementary stream.
1391 Applicable to the H264 encoder. Possible values are:
1402 - ``V4L2_MPEG_VIDEO_H264_LEVEL_1_0``
1408 - ``V4L2_MPEG_VIDEO_H264_LEVEL_1B``
1414 - ``V4L2_MPEG_VIDEO_H264_LEVEL_1_1``
1420 - ``V4L2_MPEG_VIDEO_H264_LEVEL_1_2``
1426 - ``V4L2_MPEG_VIDEO_H264_LEVEL_1_3``
1432 - ``V4L2_MPEG_VIDEO_H264_LEVEL_2_0``
1438 - ``V4L2_MPEG_VIDEO_H264_LEVEL_2_1``
1444 - ``V4L2_MPEG_VIDEO_H264_LEVEL_2_2``
1450 - ``V4L2_MPEG_VIDEO_H264_LEVEL_3_0``
1456 - ``V4L2_MPEG_VIDEO_H264_LEVEL_3_1``
1462 - ``V4L2_MPEG_VIDEO_H264_LEVEL_3_2``
1468 - ``V4L2_MPEG_VIDEO_H264_LEVEL_4_0``
1474 - ``V4L2_MPEG_VIDEO_H264_LEVEL_4_1``
1480 - ``V4L2_MPEG_VIDEO_H264_LEVEL_4_2``
1486 - ``V4L2_MPEG_VIDEO_H264_LEVEL_5_0``
1492 - ``V4L2_MPEG_VIDEO_H264_LEVEL_5_1``
1498 .. _v4l2-mpeg-video-mpeg4-level:
1500 ``V4L2_CID_MPEG_VIDEO_MPEG4_LEVEL``
1503 enum v4l2_mpeg_video_mpeg4_level -
1504 The level information for the MPEG4 elementary stream. Applicable to
1505 the MPEG4 encoder. Possible values are:
1516 - ``V4L2_MPEG_VIDEO_LEVEL_0``
1522 - ``V4L2_MPEG_VIDEO_LEVEL_0B``
1528 - ``V4L2_MPEG_VIDEO_LEVEL_1``
1534 - ``V4L2_MPEG_VIDEO_LEVEL_2``
1540 - ``V4L2_MPEG_VIDEO_LEVEL_3``
1546 - ``V4L2_MPEG_VIDEO_LEVEL_3B``
1552 - ``V4L2_MPEG_VIDEO_LEVEL_4``
1558 - ``V4L2_MPEG_VIDEO_LEVEL_5``
1564 .. _v4l2-mpeg-video-h264-profile:
1566 ``V4L2_CID_MPEG_VIDEO_H264_PROFILE``
1569 enum v4l2_mpeg_video_h264_profile -
1570 The profile information for H264. Applicable to the H264 encoder.
1571 Possible values are:
1582 - ``V4L2_MPEG_VIDEO_H264_PROFILE_BASELINE``
1588 - ``V4L2_MPEG_VIDEO_H264_PROFILE_CONSTRAINED_BASELINE``
1590 - Constrained Baseline profile
1594 - ``V4L2_MPEG_VIDEO_H264_PROFILE_MAIN``
1600 - ``V4L2_MPEG_VIDEO_H264_PROFILE_EXTENDED``
1606 - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH``
1612 - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_10``
1618 - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_422``
1624 - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_444_PREDICTIVE``
1626 - High 444 Predictive profile
1630 - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_10_INTRA``
1632 - High 10 Intra profile
1636 - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_422_INTRA``
1638 - High 422 Intra profile
1642 - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_444_INTRA``
1644 - High 444 Intra profile
1648 - ``V4L2_MPEG_VIDEO_H264_PROFILE_CAVLC_444_INTRA``
1650 - CAVLC 444 Intra profile
1654 - ``V4L2_MPEG_VIDEO_H264_PROFILE_SCALABLE_BASELINE``
1656 - Scalable Baseline profile
1660 - ``V4L2_MPEG_VIDEO_H264_PROFILE_SCALABLE_HIGH``
1662 - Scalable High profile
1666 - ``V4L2_MPEG_VIDEO_H264_PROFILE_SCALABLE_HIGH_INTRA``
1668 - Scalable High Intra profile
1672 - ``V4L2_MPEG_VIDEO_H264_PROFILE_STEREO_HIGH``
1674 - Stereo High profile
1678 - ``V4L2_MPEG_VIDEO_H264_PROFILE_MULTIVIEW_HIGH``
1680 - Multiview High profile
1684 .. _v4l2-mpeg-video-mpeg4-profile:
1686 ``V4L2_CID_MPEG_VIDEO_MPEG4_PROFILE``
1689 enum v4l2_mpeg_video_mpeg4_profile -
1690 The profile information for MPEG4. Applicable to the MPEG4 encoder.
1691 Possible values are:
1702 - ``V4L2_MPEG_VIDEO_PROFILE_SIMPLE``
1708 - ``V4L2_MPEG_VIDEO_PROFILE_ADVANCED_SIMPLE``
1710 - Advanced Simple profile
1714 - ``V4L2_MPEG_VIDEO_PROFILE_CORE``
1720 - ``V4L2_MPEG_VIDEO_PROFILE_SIMPLE_SCALABLE``
1722 - Simple Scalable profile
1726 - ``V4L2_MPEG_VIDEO_PROFILE_ADVANCED_CODING_EFFICIENCY``
1732 ``V4L2_CID_MPEG_VIDEO_MAX_REF_PIC (integer)``
1733 The maximum number of reference pictures used for encoding.
1734 Applicable to the encoder.
1736 .. _v4l2-mpeg-video-multi-slice-mode:
1738 ``V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MODE``
1741 enum v4l2_mpeg_video_multi_slice_mode -
1742 Determines how the encoder should handle division of frame into
1743 slices. Applicable to the encoder. Possible values are:
1747 .. tabularcolumns:: |p{8.7cm}|p{8.8cm}|
1756 - ``V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_SINGLE``
1758 - Single slice per frame.
1762 - ``V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_MAX_MB``
1764 - Multiple slices with set maximum number of macroblocks per slice.
1768 - ``V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_MAX_BYTES``
1770 - Multiple slice with set maximum size in bytes per slice.
1774 ``V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MAX_MB (integer)``
1775 The maximum number of macroblocks in a slice. Used when
1776 ``V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MODE`` is set to
1777 ``V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_MAX_MB``. Applicable to the
1780 ``V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MAX_BYTES (integer)``
1781 The maximum size of a slice in bytes. Used when
1782 ``V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MODE`` is set to
1783 ``V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_MAX_BYTES``. Applicable to the
1786 .. _v4l2-mpeg-video-h264-loop-filter-mode:
1788 ``V4L2_CID_MPEG_VIDEO_H264_LOOP_FILTER_MODE``
1791 enum v4l2_mpeg_video_h264_loop_filter_mode -
1792 Loop filter mode for H264 encoder. Possible values are:
1796 .. tabularcolumns:: |p{14.0cm}|p{3.5cm}|
1804 - ``V4L2_MPEG_VIDEO_H264_LOOP_FILTER_MODE_ENABLED``
1806 - Loop filter is enabled.
1810 - ``V4L2_MPEG_VIDEO_H264_LOOP_FILTER_MODE_DISABLED``
1812 - Loop filter is disabled.
1816 - ``V4L2_MPEG_VIDEO_H264_LOOP_FILTER_MODE_DISABLED_AT_SLICE_BOUNDARY``
1818 - Loop filter is disabled at the slice boundary.
1822 ``V4L2_CID_MPEG_VIDEO_H264_LOOP_FILTER_ALPHA (integer)``
1823 Loop filter alpha coefficient, defined in the H264 standard.
1824 Applicable to the H264 encoder.
1826 ``V4L2_CID_MPEG_VIDEO_H264_LOOP_FILTER_BETA (integer)``
1827 Loop filter beta coefficient, defined in the H264 standard.
1828 Applicable to the H264 encoder.
1830 .. _v4l2-mpeg-video-h264-entropy-mode:
1832 ``V4L2_CID_MPEG_VIDEO_H264_ENTROPY_MODE``
1835 enum v4l2_mpeg_video_h264_entropy_mode -
1836 Entropy coding mode for H264 - CABAC/CAVALC. Applicable to the H264
1837 encoder. Possible values are:
1848 - ``V4L2_MPEG_VIDEO_H264_ENTROPY_MODE_CAVLC``
1850 - Use CAVLC entropy coding.
1854 - ``V4L2_MPEG_VIDEO_H264_ENTROPY_MODE_CABAC``
1856 - Use CABAC entropy coding.
1860 ``V4L2_CID_MPEG_VIDEO_H264_8X8_TRANSFORM (boolean)``
1861 Enable 8X8 transform for H264. Applicable to the H264 encoder.
1863 ``V4L2_CID_MPEG_VIDEO_CYCLIC_INTRA_REFRESH_MB (integer)``
1864 Cyclic intra macroblock refresh. This is the number of continuous
1865 macroblocks refreshed every frame. Each frame a successive set of
1866 macroblocks is refreshed until the cycle completes and starts from
1867 the top of the frame. Applicable to H264, H263 and MPEG4 encoder.
1869 ``V4L2_CID_MPEG_VIDEO_FRAME_RC_ENABLE (boolean)``
1870 Frame level rate control enable. If this control is disabled then
1871 the quantization parameter for each frame type is constant and set
1872 with appropriate controls (e.g.
1873 ``V4L2_CID_MPEG_VIDEO_H263_I_FRAME_QP``). If frame rate control is
1874 enabled then quantization parameter is adjusted to meet the chosen
1875 bitrate. Minimum and maximum value for the quantization parameter
1876 can be set with appropriate controls (e.g.
1877 ``V4L2_CID_MPEG_VIDEO_H263_MIN_QP``). Applicable to encoders.
1879 ``V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE (boolean)``
1880 Macroblock level rate control enable. Applicable to the MPEG4 and
1883 ``V4L2_CID_MPEG_VIDEO_MPEG4_QPEL (boolean)``
1884 Quarter pixel motion estimation for MPEG4. Applicable to the MPEG4
1887 ``V4L2_CID_MPEG_VIDEO_H263_I_FRAME_QP (integer)``
1888 Quantization parameter for an I frame for H263. Valid range: from 1
1891 ``V4L2_CID_MPEG_VIDEO_H263_MIN_QP (integer)``
1892 Minimum quantization parameter for H263. Valid range: from 1 to 31.
1894 ``V4L2_CID_MPEG_VIDEO_H263_MAX_QP (integer)``
1895 Maximum quantization parameter for H263. Valid range: from 1 to 31.
1897 ``V4L2_CID_MPEG_VIDEO_H263_P_FRAME_QP (integer)``
1898 Quantization parameter for an P frame for H263. Valid range: from 1
1901 ``V4L2_CID_MPEG_VIDEO_H263_B_FRAME_QP (integer)``
1902 Quantization parameter for an B frame for H263. Valid range: from 1
1905 ``V4L2_CID_MPEG_VIDEO_H264_I_FRAME_QP (integer)``
1906 Quantization parameter for an I frame for H264. Valid range: from 0
1909 ``V4L2_CID_MPEG_VIDEO_H264_MIN_QP (integer)``
1910 Minimum quantization parameter for H264. Valid range: from 0 to 51.
1912 ``V4L2_CID_MPEG_VIDEO_H264_MAX_QP (integer)``
1913 Maximum quantization parameter for H264. Valid range: from 0 to 51.
1915 ``V4L2_CID_MPEG_VIDEO_H264_P_FRAME_QP (integer)``
1916 Quantization parameter for an P frame for H264. Valid range: from 0
1919 ``V4L2_CID_MPEG_VIDEO_H264_B_FRAME_QP (integer)``
1920 Quantization parameter for an B frame for H264. Valid range: from 0
1923 ``V4L2_CID_MPEG_VIDEO_MPEG4_I_FRAME_QP (integer)``
1924 Quantization parameter for an I frame for MPEG4. Valid range: from 1
1927 ``V4L2_CID_MPEG_VIDEO_MPEG4_MIN_QP (integer)``
1928 Minimum quantization parameter for MPEG4. Valid range: from 1 to 31.
1930 ``V4L2_CID_MPEG_VIDEO_MPEG4_MAX_QP (integer)``
1931 Maximum quantization parameter for MPEG4. Valid range: from 1 to 31.
1933 ``V4L2_CID_MPEG_VIDEO_MPEG4_P_FRAME_QP (integer)``
1934 Quantization parameter for an P frame for MPEG4. Valid range: from 1
1937 ``V4L2_CID_MPEG_VIDEO_MPEG4_B_FRAME_QP (integer)``
1938 Quantization parameter for an B frame for MPEG4. Valid range: from 1
1941 ``V4L2_CID_MPEG_VIDEO_VBV_SIZE (integer)``
1942 The Video Buffer Verifier size in kilobytes, it is used as a
1943 limitation of frame skip. The VBV is defined in the standard as a
1944 mean to verify that the produced stream will be successfully
1945 decoded. The standard describes it as "Part of a hypothetical
1946 decoder that is conceptually connected to the output of the encoder.
1947 Its purpose is to provide a constraint on the variability of the
1948 data rate that an encoder or editing process may produce.".
1949 Applicable to the MPEG1, MPEG2, MPEG4 encoders.
1951 .. _v4l2-mpeg-video-vbv-delay:
1953 ``V4L2_CID_MPEG_VIDEO_VBV_DELAY (integer)``
1954 Sets the initial delay in milliseconds for VBV buffer control.
1956 .. _v4l2-mpeg-video-hor-search-range:
1958 ``V4L2_CID_MPEG_VIDEO_MV_H_SEARCH_RANGE (integer)``
1959 Horizontal search range defines maximum horizontal search area in
1960 pixels to search and match for the present Macroblock (MB) in the
1961 reference picture. This V4L2 control macro is used to set horizontal
1962 search range for motion estimation module in video encoder.
1964 .. _v4l2-mpeg-video-vert-search-range:
1966 ``V4L2_CID_MPEG_VIDEO_MV_V_SEARCH_RANGE (integer)``
1967 Vertical search range defines maximum vertical search area in pixels
1968 to search and match for the present Macroblock (MB) in the reference
1969 picture. This V4L2 control macro is used to set vertical search
1970 range for motion estimation module in video encoder.
1972 .. _v4l2-mpeg-video-force-key-frame:
1974 ``V4L2_CID_MPEG_VIDEO_FORCE_KEY_FRAME (button)``
1975 Force a key frame for the next queued buffer. Applicable to
1976 encoders. This is a general, codec-agnostic keyframe control.
1978 ``V4L2_CID_MPEG_VIDEO_H264_CPB_SIZE (integer)``
1979 The Coded Picture Buffer size in kilobytes, it is used as a
1980 limitation of frame skip. The CPB is defined in the H264 standard as
1981 a mean to verify that the produced stream will be successfully
1982 decoded. Applicable to the H264 encoder.
1984 ``V4L2_CID_MPEG_VIDEO_H264_I_PERIOD (integer)``
1985 Period between I-frames in the open GOP for H264. In case of an open
1986 GOP this is the period between two I-frames. The period between IDR
1987 (Instantaneous Decoding Refresh) frames is taken from the GOP_SIZE
1988 control. An IDR frame, which stands for Instantaneous Decoding
1989 Refresh is an I-frame after which no prior frames are referenced.
1990 This means that a stream can be restarted from an IDR frame without
1991 the need to store or decode any previous frames. Applicable to the
1994 .. _v4l2-mpeg-video-header-mode:
1996 ``V4L2_CID_MPEG_VIDEO_HEADER_MODE``
1999 enum v4l2_mpeg_video_header_mode -
2000 Determines whether the header is returned as the first buffer or is
2001 it returned together with the first frame. Applicable to encoders.
2002 Possible values are:
2006 .. tabularcolumns:: |p{10.3cm}|p{7.2cm}|
2015 - ``V4L2_MPEG_VIDEO_HEADER_MODE_SEPARATE``
2017 - The stream header is returned separately in the first buffer.
2021 - ``V4L2_MPEG_VIDEO_HEADER_MODE_JOINED_WITH_1ST_FRAME``
2023 - The stream header is returned together with the first encoded
2028 ``V4L2_CID_MPEG_VIDEO_REPEAT_SEQ_HEADER (boolean)``
2029 Repeat the video sequence headers. Repeating these headers makes
2030 random access to the video stream easier. Applicable to the MPEG1, 2
2033 ``V4L2_CID_MPEG_VIDEO_DECODER_MPEG4_DEBLOCK_FILTER (boolean)``
2034 Enabled the deblocking post processing filter for MPEG4 decoder.
2035 Applicable to the MPEG4 decoder.
2037 ``V4L2_CID_MPEG_VIDEO_MPEG4_VOP_TIME_RES (integer)``
2038 vop_time_increment_resolution value for MPEG4. Applicable to the
2041 ``V4L2_CID_MPEG_VIDEO_MPEG4_VOP_TIME_INC (integer)``
2042 vop_time_increment value for MPEG4. Applicable to the MPEG4
2045 ``V4L2_CID_MPEG_VIDEO_H264_SEI_FRAME_PACKING (boolean)``
2046 Enable generation of frame packing supplemental enhancement
2047 information in the encoded bitstream. The frame packing SEI message
2048 contains the arrangement of L and R planes for 3D viewing.
2049 Applicable to the H264 encoder.
2051 ``V4L2_CID_MPEG_VIDEO_H264_SEI_FP_CURRENT_FRAME_0 (boolean)``
2052 Sets current frame as frame0 in frame packing SEI. Applicable to the
2055 .. _v4l2-mpeg-video-h264-sei-fp-arrangement-type:
2057 ``V4L2_CID_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE``
2060 enum v4l2_mpeg_video_h264_sei_fp_arrangement_type -
2061 Frame packing arrangement type for H264 SEI. Applicable to the H264
2062 encoder. Possible values are:
2064 .. tabularcolumns:: |p{12cm}|p{5.5cm}|
2072 - ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_CHEKERBOARD``
2074 - Pixels are alternatively from L and R.
2078 - ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_COLUMN``
2080 - L and R are interlaced by column.
2084 - ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_ROW``
2086 - L and R are interlaced by row.
2090 - ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_SIDE_BY_SIDE``
2092 - L is on the left, R on the right.
2096 - ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_TOP_BOTTOM``
2098 - L is on top, R on bottom.
2102 - ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_TEMPORAL``
2104 - One view per frame.
2108 ``V4L2_CID_MPEG_VIDEO_H264_FMO (boolean)``
2109 Enables flexible macroblock ordering in the encoded bitstream. It is
2110 a technique used for restructuring the ordering of macroblocks in
2111 pictures. Applicable to the H264 encoder.
2113 .. _v4l2-mpeg-video-h264-fmo-map-type:
2115 ``V4L2_CID_MPEG_VIDEO_H264_FMO_MAP_TYPE``
2118 enum v4l2_mpeg_video_h264_fmo_map_type -
2119 When using FMO, the map type divides the image in different scan
2120 patterns of macroblocks. Applicable to the H264 encoder. Possible
2123 .. tabularcolumns:: |p{12.5cm}|p{5.0cm}|
2131 - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_INTERLEAVED_SLICES``
2133 - Slices are interleaved one after other with macroblocks in run
2138 - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_SCATTERED_SLICES``
2140 - Scatters the macroblocks based on a mathematical function known to
2141 both encoder and decoder.
2145 - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_FOREGROUND_WITH_LEFT_OVER``
2147 - Macroblocks arranged in rectangular areas or regions of interest.
2151 - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_BOX_OUT``
2153 - Slice groups grow in a cyclic way from centre to outwards.
2157 - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_RASTER_SCAN``
2159 - Slice groups grow in raster scan pattern from left to right.
2163 - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_WIPE_SCAN``
2165 - Slice groups grow in wipe scan pattern from top to bottom.
2169 - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_EXPLICIT``
2171 - User defined map type.
2175 ``V4L2_CID_MPEG_VIDEO_H264_FMO_SLICE_GROUP (integer)``
2176 Number of slice groups in FMO. Applicable to the H264 encoder.
2178 .. _v4l2-mpeg-video-h264-fmo-change-direction:
2180 ``V4L2_CID_MPEG_VIDEO_H264_FMO_CHANGE_DIRECTION``
2183 enum v4l2_mpeg_video_h264_fmo_change_dir -
2184 Specifies a direction of the slice group change for raster and wipe
2185 maps. Applicable to the H264 encoder. Possible values are:
2196 - ``V4L2_MPEG_VIDEO_H264_FMO_CHANGE_DIR_RIGHT``
2198 - Raster scan or wipe right.
2202 - ``V4L2_MPEG_VIDEO_H264_FMO_CHANGE_DIR_LEFT``
2204 - Reverse raster scan or wipe left.
2208 ``V4L2_CID_MPEG_VIDEO_H264_FMO_CHANGE_RATE (integer)``
2209 Specifies the size of the first slice group for raster and wipe map.
2210 Applicable to the H264 encoder.
2212 ``V4L2_CID_MPEG_VIDEO_H264_FMO_RUN_LENGTH (integer)``
2213 Specifies the number of consecutive macroblocks for the interleaved
2214 map. Applicable to the H264 encoder.
2216 ``V4L2_CID_MPEG_VIDEO_H264_ASO (boolean)``
2217 Enables arbitrary slice ordering in encoded bitstream. Applicable to
2220 ``V4L2_CID_MPEG_VIDEO_H264_ASO_SLICE_ORDER (integer)``
2221 Specifies the slice order in ASO. Applicable to the H264 encoder.
2222 The supplied 32-bit integer is interpreted as follows (bit 0 = least
2242 - Slice position or order
2246 ``V4L2_CID_MPEG_VIDEO_H264_HIERARCHICAL_CODING (boolean)``
2247 Enables H264 hierarchical coding. Applicable to the H264 encoder.
2249 .. _v4l2-mpeg-video-h264-hierarchical-coding-type:
2251 ``V4L2_CID_MPEG_VIDEO_H264_HIERARCHICAL_CODING_TYPE``
2254 enum v4l2_mpeg_video_h264_hierarchical_coding_type -
2255 Specifies the hierarchical coding type. Applicable to the H264
2256 encoder. Possible values are:
2267 - ``V4L2_MPEG_VIDEO_H264_HIERARCHICAL_CODING_B``
2269 - Hierarchical B coding.
2273 - ``V4L2_MPEG_VIDEO_H264_HIERARCHICAL_CODING_P``
2275 - Hierarchical P coding.
2279 ``V4L2_CID_MPEG_VIDEO_H264_HIERARCHICAL_CODING_LAYER (integer)``
2280 Specifies the number of hierarchical coding layers. Applicable to
2283 ``V4L2_CID_MPEG_VIDEO_H264_HIERARCHICAL_CODING_LAYER_QP (integer)``
2284 Specifies a user defined QP for each layer. Applicable to the H264
2285 encoder. The supplied 32-bit integer is interpreted as follows (bit
2286 0 = least significant bit):
2310 MFC 5.1 MPEG Controls
2311 ---------------------
2313 The following MPEG class controls deal with MPEG decoding and encoding
2314 settings that are specific to the Multi Format Codec 5.1 device present
2315 in the S5P family of SoCs by Samsung.
2318 .. _mfc51-control-id:
2323 ``V4L2_CID_MPEG_MFC51_VIDEO_DECODER_H264_DISPLAY_DELAY_ENABLE (boolean)``
2324 If the display delay is enabled then the decoder is forced to return
2325 a CAPTURE buffer (decoded frame) after processing a certain number
2326 of OUTPUT buffers. The delay can be set through
2327 ``V4L2_CID_MPEG_MFC51_VIDEO_DECODER_H264_DISPLAY_DELAY``. This
2328 feature can be used for example for generating thumbnails of videos.
2329 Applicable to the H264 decoder.
2331 ``V4L2_CID_MPEG_MFC51_VIDEO_DECODER_H264_DISPLAY_DELAY (integer)``
2332 Display delay value for H264 decoder. The decoder is forced to
2333 return a decoded frame after the set 'display delay' number of
2334 frames. If this number is low it may result in frames returned out
2335 of dispaly order, in addition the hardware may still be using the
2336 returned buffer as a reference picture for subsequent frames.
2338 ``V4L2_CID_MPEG_MFC51_VIDEO_H264_NUM_REF_PIC_FOR_P (integer)``
2339 The number of reference pictures used for encoding a P picture.
2340 Applicable to the H264 encoder.
2342 ``V4L2_CID_MPEG_MFC51_VIDEO_PADDING (boolean)``
2343 Padding enable in the encoder - use a color instead of repeating
2344 border pixels. Applicable to encoders.
2346 ``V4L2_CID_MPEG_MFC51_VIDEO_PADDING_YUV (integer)``
2347 Padding color in the encoder. Applicable to encoders. The supplied
2348 32-bit integer is interpreted as follows (bit 0 = least significant
2362 - V chrominance information
2368 - U chrominance information
2374 - Y luminance information
2384 ``V4L2_CID_MPEG_MFC51_VIDEO_RC_REACTION_COEFF (integer)``
2385 Reaction coefficient for MFC rate control. Applicable to encoders.
2389 #. Valid only when the frame level RC is enabled.
2391 #. For tight CBR, this field must be small (ex. 2 ~ 10). For
2392 VBR, this field must be large (ex. 100 ~ 1000).
2394 #. It is not recommended to use the greater number than
2395 FRAME_RATE * (10^9 / BIT_RATE).
2397 ``V4L2_CID_MPEG_MFC51_VIDEO_H264_ADAPTIVE_RC_DARK (boolean)``
2398 Adaptive rate control for dark region. Valid only when H.264 and
2399 macroblock level RC is enabled
2400 (``V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE``). Applicable to the H264
2403 ``V4L2_CID_MPEG_MFC51_VIDEO_H264_ADAPTIVE_RC_SMOOTH (boolean)``
2404 Adaptive rate control for smooth region. Valid only when H.264 and
2405 macroblock level RC is enabled
2406 (``V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE``). Applicable to the H264
2409 ``V4L2_CID_MPEG_MFC51_VIDEO_H264_ADAPTIVE_RC_STATIC (boolean)``
2410 Adaptive rate control for static region. Valid only when H.264 and
2411 macroblock level RC is enabled
2412 (``V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE``). Applicable to the H264
2415 ``V4L2_CID_MPEG_MFC51_VIDEO_H264_ADAPTIVE_RC_ACTIVITY (boolean)``
2416 Adaptive rate control for activity region. Valid only when H.264 and
2417 macroblock level RC is enabled
2418 (``V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE``). Applicable to the H264
2421 .. _v4l2-mpeg-mfc51-video-frame-skip-mode:
2423 ``V4L2_CID_MPEG_MFC51_VIDEO_FRAME_SKIP_MODE``
2426 enum v4l2_mpeg_mfc51_video_frame_skip_mode -
2427 Indicates in what conditions the encoder should skip frames. If
2428 encoding a frame would cause the encoded stream to be larger then a
2429 chosen data limit then the frame will be skipped. Possible values
2433 .. tabularcolumns:: |p{9.0cm}|p{8.5cm}|
2441 - ``V4L2_MPEG_MFC51_FRAME_SKIP_MODE_DISABLED``
2443 - Frame skip mode is disabled.
2447 - ``V4L2_MPEG_MFC51_FRAME_SKIP_MODE_LEVEL_LIMIT``
2449 - Frame skip mode enabled and buffer limit is set by the chosen
2450 level and is defined by the standard.
2454 - ``V4L2_MPEG_MFC51_FRAME_SKIP_MODE_BUF_LIMIT``
2456 - Frame skip mode enabled and buffer limit is set by the VBV
2457 (MPEG1/2/4) or CPB (H264) buffer size control.
2461 ``V4L2_CID_MPEG_MFC51_VIDEO_RC_FIXED_TARGET_BIT (integer)``
2462 Enable rate-control with fixed target bit. If this setting is
2463 enabled, then the rate control logic of the encoder will calculate
2464 the average bitrate for a GOP and keep it below or equal the set
2465 bitrate target. Otherwise the rate control logic calculates the
2466 overall average bitrate for the stream and keeps it below or equal
2467 to the set bitrate. In the first case the average bitrate for the
2468 whole stream will be smaller then the set bitrate. This is caused
2469 because the average is calculated for smaller number of frames, on
2470 the other hand enabling this setting will ensure that the stream
2471 will meet tight bandwidth constraints. Applicable to encoders.
2473 .. _v4l2-mpeg-mfc51-video-force-frame-type:
2475 ``V4L2_CID_MPEG_MFC51_VIDEO_FORCE_FRAME_TYPE``
2478 enum v4l2_mpeg_mfc51_video_force_frame_type -
2479 Force a frame type for the next queued buffer. Applicable to
2480 encoders. Possible values are:
2491 - ``V4L2_MPEG_MFC51_FORCE_FRAME_TYPE_DISABLED``
2493 - Forcing a specific frame type disabled.
2497 - ``V4L2_MPEG_MFC51_FORCE_FRAME_TYPE_I_FRAME``
2503 - ``V4L2_MPEG_MFC51_FORCE_FRAME_TYPE_NOT_CODED``
2505 - Force a non-coded frame.
2510 CX2341x MPEG Controls
2511 ---------------------
2513 The following MPEG class controls deal with MPEG encoding settings that
2514 are specific to the Conexant CX23415 and CX23416 MPEG encoding chips.
2517 .. _cx2341x-control-id:
2522 .. _v4l2-mpeg-cx2341x-video-spatial-filter-mode:
2524 ``V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE``
2527 enum v4l2_mpeg_cx2341x_video_spatial_filter_mode -
2528 Sets the Spatial Filter mode (default ``MANUAL``). Possible values
2540 - ``V4L2_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE_MANUAL``
2542 - Choose the filter manually
2546 - ``V4L2_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE_AUTO``
2548 - Choose the filter automatically
2552 ``V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER (integer (0-15))``
2553 The setting for the Spatial Filter. 0 = off, 15 = maximum. (Default
2556 .. _luma-spatial-filter-type:
2558 ``V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE``
2561 enum v4l2_mpeg_cx2341x_video_luma_spatial_filter_type -
2562 Select the algorithm to use for the Luma Spatial Filter (default
2563 ``1D_HOR``). Possible values:
2567 .. tabularcolumns:: |p{14.5cm}|p{3.0cm}|
2576 - ``V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_OFF``
2582 - ``V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_1D_HOR``
2584 - One-dimensional horizontal
2588 - ``V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_1D_VERT``
2590 - One-dimensional vertical
2594 - ``V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_2D_HV_SEPARABLE``
2596 - Two-dimensional separable
2600 - ``V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_2D_SYM_NON_SEPARABLE``
2602 - Two-dimensional symmetrical non-separable
2606 .. _chroma-spatial-filter-type:
2608 ``V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE``
2611 enum v4l2_mpeg_cx2341x_video_chroma_spatial_filter_type -
2612 Select the algorithm for the Chroma Spatial Filter (default
2613 ``1D_HOR``). Possible values are:
2624 - ``V4L2_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE_OFF``
2630 - ``V4L2_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE_1D_HOR``
2632 - One-dimensional horizontal
2636 .. _v4l2-mpeg-cx2341x-video-temporal-filter-mode:
2638 ``V4L2_CID_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE``
2641 enum v4l2_mpeg_cx2341x_video_temporal_filter_mode -
2642 Sets the Temporal Filter mode (default ``MANUAL``). Possible values
2654 - ``V4L2_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE_MANUAL``
2656 - Choose the filter manually
2660 - ``V4L2_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE_AUTO``
2662 - Choose the filter automatically
2666 ``V4L2_CID_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER (integer (0-31))``
2667 The setting for the Temporal Filter. 0 = off, 31 = maximum. (Default
2668 is 8 for full-scale capturing and 0 for scaled capturing.)
2670 .. _v4l2-mpeg-cx2341x-video-median-filter-type:
2672 ``V4L2_CID_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE``
2675 enum v4l2_mpeg_cx2341x_video_median_filter_type -
2676 Median Filter Type (default ``OFF``). Possible values are:
2687 - ``V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_OFF``
2693 - ``V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_HOR``
2699 - ``V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_VERT``
2705 - ``V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_HOR_VERT``
2707 - Horizontal and vertical filter
2711 - ``V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_DIAG``
2717 ``V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_MEDIAN_FILTER_BOTTOM (integer (0-255))``
2718 Threshold above which the luminance median filter is enabled
2721 ``V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_MEDIAN_FILTER_TOP (integer (0-255))``
2722 Threshold below which the luminance median filter is enabled
2725 ``V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_MEDIAN_FILTER_BOTTOM (integer (0-255))``
2726 Threshold above which the chroma median filter is enabled (default
2729 ``V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_MEDIAN_FILTER_TOP (integer (0-255))``
2730 Threshold below which the chroma median filter is enabled (default
2733 ``V4L2_CID_MPEG_CX2341X_STREAM_INSERT_NAV_PACKETS (boolean)``
2734 The CX2341X MPEG encoder can insert one empty MPEG-2 PES packet into
2735 the stream between every four video frames. The packet size is 2048
2736 bytes, including the packet_start_code_prefix and stream_id
2737 fields. The stream_id is 0xBF (private stream 2). The payload
2738 consists of 0x00 bytes, to be filled in by the application. 0 = do
2739 not insert, 1 = insert packets.
2742 VPX Control Reference
2743 ---------------------
2745 The VPX controls include controls for encoding parameters of VPx video
2754 .. _v4l2-vpx-num-partitions:
2756 ``V4L2_CID_MPEG_VIDEO_VPX_NUM_PARTITIONS``
2759 enum v4l2_vp8_num_partitions -
2760 The number of token partitions to use in VP8 encoder. Possible
2772 - ``V4L2_CID_MPEG_VIDEO_VPX_1_PARTITION``
2774 - 1 coefficient partition
2778 - ``V4L2_CID_MPEG_VIDEO_VPX_2_PARTITIONS``
2780 - 2 coefficient partitions
2784 - ``V4L2_CID_MPEG_VIDEO_VPX_4_PARTITIONS``
2786 - 4 coefficient partitions
2790 - ``V4L2_CID_MPEG_VIDEO_VPX_8_PARTITIONS``
2792 - 8 coefficient partitions
2796 ``V4L2_CID_MPEG_VIDEO_VPX_IMD_DISABLE_4X4 (boolean)``
2797 Setting this prevents intra 4x4 mode in the intra mode decision.
2799 .. _v4l2-vpx-num-ref-frames:
2801 ``V4L2_CID_MPEG_VIDEO_VPX_NUM_REF_FRAMES``
2804 enum v4l2_vp8_num_ref_frames -
2805 The number of reference pictures for encoding P frames. Possible
2808 .. tabularcolumns:: |p{7.9cm}|p{9.6cm}|
2816 - ``V4L2_CID_MPEG_VIDEO_VPX_1_REF_FRAME``
2818 - Last encoded frame will be searched
2822 - ``V4L2_CID_MPEG_VIDEO_VPX_2_REF_FRAME``
2824 - Two frames will be searched among the last encoded frame, the
2825 golden frame and the alternate reference (altref) frame. The
2826 encoder implementation will decide which two are chosen.
2830 - ``V4L2_CID_MPEG_VIDEO_VPX_3_REF_FRAME``
2832 - The last encoded frame, the golden frame and the altref frame will
2837 ``V4L2_CID_MPEG_VIDEO_VPX_FILTER_LEVEL (integer)``
2838 Indicates the loop filter level. The adjustment of the loop filter
2839 level is done via a delta value against a baseline loop filter
2842 ``V4L2_CID_MPEG_VIDEO_VPX_FILTER_SHARPNESS (integer)``
2843 This parameter affects the loop filter. Anything above zero weakens
2844 the deblocking effect on the loop filter.
2846 ``V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_REF_PERIOD (integer)``
2847 Sets the refresh period for the golden frame. The period is defined
2848 in number of frames. For a value of 'n', every nth frame starting
2849 from the first key frame will be taken as a golden frame. For eg.
2850 for encoding sequence of 0, 1, 2, 3, 4, 5, 6, 7 where the golden
2851 frame refresh period is set as 4, the frames 0, 4, 8 etc will be
2852 taken as the golden frames as frame 0 is always a key frame.
2854 .. _v4l2-vpx-golden-frame-sel:
2856 ``V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_SEL``
2859 enum v4l2_vp8_golden_frame_sel -
2860 Selects the golden frame for encoding. Possible values are:
2864 \begin{adjustbox}{width=\columnwidth}
2866 .. tabularcolumns:: |p{11.0cm}|p{10.0cm}|
2874 - ``V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_USE_PREV``
2876 - Use the (n-2)th frame as a golden frame, current frame index being
2881 - ``V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_USE_REF_PERIOD``
2883 - Use the previous specific frame indicated by
2884 ``V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_REF_PERIOD`` as a
2892 ``V4L2_CID_MPEG_VIDEO_VPX_MIN_QP (integer)``
2893 Minimum quantization parameter for VP8.
2895 ``V4L2_CID_MPEG_VIDEO_VPX_MAX_QP (integer)``
2896 Maximum quantization parameter for VP8.
2898 ``V4L2_CID_MPEG_VIDEO_VPX_I_FRAME_QP (integer)``
2899 Quantization parameter for an I frame for VP8.
2901 ``V4L2_CID_MPEG_VIDEO_VPX_P_FRAME_QP (integer)``
2902 Quantization parameter for a P frame for VP8.
2904 ``V4L2_CID_MPEG_VIDEO_VPX_PROFILE (integer)``
2905 Select the desired profile for VPx encoder. Acceptable values are 0,
2906 1, 2 and 3 corresponding to encoder profiles 0, 1, 2 and 3.
2909 .. _camera-controls:
2911 Camera Control Reference
2912 ========================
2914 The Camera class includes controls for mechanical (or equivalent
2915 digital) features of a device such as controllable lenses or sensors.
2918 .. _camera-control-id:
2923 ``V4L2_CID_CAMERA_CLASS (class)``
2924 The Camera class descriptor. Calling
2925 :ref:`VIDIOC_QUERYCTRL` for this control will
2926 return a description of this control class.
2928 .. _v4l2-exposure-auto-type:
2930 ``V4L2_CID_EXPOSURE_AUTO``
2933 enum v4l2_exposure_auto_type -
2934 Enables automatic adjustments of the exposure time and/or iris
2935 aperture. The effect of manual changes of the exposure time or iris
2936 aperture while these features are enabled is undefined, drivers
2937 should ignore such requests. Possible values are:
2948 - ``V4L2_EXPOSURE_AUTO``
2950 - Automatic exposure time, automatic iris aperture.
2954 - ``V4L2_EXPOSURE_MANUAL``
2956 - Manual exposure time, manual iris.
2960 - ``V4L2_EXPOSURE_SHUTTER_PRIORITY``
2962 - Manual exposure time, auto iris.
2966 - ``V4L2_EXPOSURE_APERTURE_PRIORITY``
2968 - Auto exposure time, manual iris.
2972 ``V4L2_CID_EXPOSURE_ABSOLUTE (integer)``
2973 Determines the exposure time of the camera sensor. The exposure time
2974 is limited by the frame interval. Drivers should interpret the
2975 values as 100 µs units, where the value 1 stands for 1/10000th of a
2976 second, 10000 for 1 second and 100000 for 10 seconds.
2978 ``V4L2_CID_EXPOSURE_AUTO_PRIORITY (boolean)``
2979 When ``V4L2_CID_EXPOSURE_AUTO`` is set to ``AUTO`` or
2980 ``APERTURE_PRIORITY``, this control determines if the device may
2981 dynamically vary the frame rate. By default this feature is disabled
2982 (0) and the frame rate must remain constant.
2984 ``V4L2_CID_EXPOSURE_BIAS (integer menu)``
2985 Determines the automatic exposure compensation, it is effective only
2986 when ``V4L2_CID_EXPOSURE_AUTO`` control is set to ``AUTO``,
2987 ``SHUTTER_PRIORITY`` or ``APERTURE_PRIORITY``. It is expressed in
2988 terms of EV, drivers should interpret the values as 0.001 EV units,
2989 where the value 1000 stands for +1 EV.
2991 Increasing the exposure compensation value is equivalent to
2992 decreasing the exposure value (EV) and will increase the amount of
2993 light at the image sensor. The camera performs the exposure
2994 compensation by adjusting absolute exposure time and/or aperture.
2996 .. _v4l2-exposure-metering:
2998 ``V4L2_CID_EXPOSURE_METERING``
3001 enum v4l2_exposure_metering -
3002 Determines how the camera measures the amount of light available for
3003 the frame exposure. Possible values are:
3005 .. tabularcolumns:: |p{8.5cm}|p{9.0cm}|
3013 - ``V4L2_EXPOSURE_METERING_AVERAGE``
3015 - Use the light information coming from the entire frame and average
3016 giving no weighting to any particular portion of the metered area.
3020 - ``V4L2_EXPOSURE_METERING_CENTER_WEIGHTED``
3022 - Average the light information coming from the entire frame giving
3023 priority to the center of the metered area.
3027 - ``V4L2_EXPOSURE_METERING_SPOT``
3029 - Measure only very small area at the center of the frame.
3033 - ``V4L2_EXPOSURE_METERING_MATRIX``
3035 - A multi-zone metering. The light intensity is measured in several
3036 points of the frame and the results are combined. The algorithm of
3037 the zones selection and their significance in calculating the
3038 final value is device dependent.
3042 ``V4L2_CID_PAN_RELATIVE (integer)``
3043 This control turns the camera horizontally by the specified amount.
3044 The unit is undefined. A positive value moves the camera to the
3045 right (clockwise when viewed from above), a negative value to the
3046 left. A value of zero does not cause motion. This is a write-only
3049 ``V4L2_CID_TILT_RELATIVE (integer)``
3050 This control turns the camera vertically by the specified amount.
3051 The unit is undefined. A positive value moves the camera up, a
3052 negative value down. A value of zero does not cause motion. This is
3053 a write-only control.
3055 ``V4L2_CID_PAN_RESET (button)``
3056 When this control is set, the camera moves horizontally to the
3059 ``V4L2_CID_TILT_RESET (button)``
3060 When this control is set, the camera moves vertically to the default
3063 ``V4L2_CID_PAN_ABSOLUTE (integer)``
3064 This control turns the camera horizontally to the specified
3065 position. Positive values move the camera to the right (clockwise
3066 when viewed from above), negative values to the left. Drivers should
3067 interpret the values as arc seconds, with valid values between -180
3068 * 3600 and +180 * 3600 inclusive.
3070 ``V4L2_CID_TILT_ABSOLUTE (integer)``
3071 This control turns the camera vertically to the specified position.
3072 Positive values move the camera up, negative values down. Drivers
3073 should interpret the values as arc seconds, with valid values
3074 between -180 * 3600 and +180 * 3600 inclusive.
3076 ``V4L2_CID_FOCUS_ABSOLUTE (integer)``
3077 This control sets the focal point of the camera to the specified
3078 position. The unit is undefined. Positive values set the focus
3079 closer to the camera, negative values towards infinity.
3081 ``V4L2_CID_FOCUS_RELATIVE (integer)``
3082 This control moves the focal point of the camera by the specified
3083 amount. The unit is undefined. Positive values move the focus closer
3084 to the camera, negative values towards infinity. This is a
3087 ``V4L2_CID_FOCUS_AUTO (boolean)``
3088 Enables continuous automatic focus adjustments. The effect of manual
3089 focus adjustments while this feature is enabled is undefined,
3090 drivers should ignore such requests.
3092 ``V4L2_CID_AUTO_FOCUS_START (button)``
3093 Starts single auto focus process. The effect of setting this control
3094 when ``V4L2_CID_FOCUS_AUTO`` is set to ``TRUE`` (1) is undefined,
3095 drivers should ignore such requests.
3097 ``V4L2_CID_AUTO_FOCUS_STOP (button)``
3098 Aborts automatic focusing started with ``V4L2_CID_AUTO_FOCUS_START``
3099 control. It is effective only when the continuous autofocus is
3100 disabled, that is when ``V4L2_CID_FOCUS_AUTO`` control is set to
3103 .. _v4l2-auto-focus-status:
3105 ``V4L2_CID_AUTO_FOCUS_STATUS (bitmask)``
3106 The automatic focus status. This is a read-only control.
3108 Setting ``V4L2_LOCK_FOCUS`` lock bit of the ``V4L2_CID_3A_LOCK``
3109 control may stop updates of the ``V4L2_CID_AUTO_FOCUS_STATUS``
3112 .. tabularcolumns:: |p{6.5cm}|p{11.0cm}|
3120 - ``V4L2_AUTO_FOCUS_STATUS_IDLE``
3122 - Automatic focus is not active.
3126 - ``V4L2_AUTO_FOCUS_STATUS_BUSY``
3128 - Automatic focusing is in progress.
3132 - ``V4L2_AUTO_FOCUS_STATUS_REACHED``
3134 - Focus has been reached.
3138 - ``V4L2_AUTO_FOCUS_STATUS_FAILED``
3140 - Automatic focus has failed, the driver will not transition from
3141 this state until another action is performed by an application.
3145 .. _v4l2-auto-focus-range:
3147 ``V4L2_CID_AUTO_FOCUS_RANGE``
3150 enum v4l2_auto_focus_range -
3151 Determines auto focus distance range for which lens may be adjusted.
3153 .. tabularcolumns:: |p{6.5cm}|p{11.0cm}|
3162 - ``V4L2_AUTO_FOCUS_RANGE_AUTO``
3164 - The camera automatically selects the focus range.
3168 - ``V4L2_AUTO_FOCUS_RANGE_NORMAL``
3170 - Normal distance range, limited for best automatic focus
3175 - ``V4L2_AUTO_FOCUS_RANGE_MACRO``
3177 - Macro (close-up) auto focus. The camera will use its minimum
3178 possible distance for auto focus.
3182 - ``V4L2_AUTO_FOCUS_RANGE_INFINITY``
3184 - The lens is set to focus on an object at infinite distance.
3188 ``V4L2_CID_ZOOM_ABSOLUTE (integer)``
3189 Specify the objective lens focal length as an absolute value. The
3190 zoom unit is driver-specific and its value should be a positive
3193 ``V4L2_CID_ZOOM_RELATIVE (integer)``
3194 Specify the objective lens focal length relatively to the current
3195 value. Positive values move the zoom lens group towards the
3196 telephoto direction, negative values towards the wide-angle
3197 direction. The zoom unit is driver-specific. This is a write-only
3200 ``V4L2_CID_ZOOM_CONTINUOUS (integer)``
3201 Move the objective lens group at the specified speed until it
3202 reaches physical device limits or until an explicit request to stop
3203 the movement. A positive value moves the zoom lens group towards the
3204 telephoto direction. A value of zero stops the zoom lens group
3205 movement. A negative value moves the zoom lens group towards the
3206 wide-angle direction. The zoom speed unit is driver-specific.
3208 ``V4L2_CID_IRIS_ABSOLUTE (integer)``
3209 This control sets the camera's aperture to the specified value. The
3210 unit is undefined. Larger values open the iris wider, smaller values
3213 ``V4L2_CID_IRIS_RELATIVE (integer)``
3214 This control modifies the camera's aperture by the specified amount.
3215 The unit is undefined. Positive values open the iris one step
3216 further, negative values close it one step further. This is a
3219 ``V4L2_CID_PRIVACY (boolean)``
3220 Prevent video from being acquired by the camera. When this control
3221 is set to ``TRUE`` (1), no image can be captured by the camera.
3222 Common means to enforce privacy are mechanical obturation of the
3223 sensor and firmware image processing, but the device is not
3224 restricted to these methods. Devices that implement the privacy
3225 control must support read access and may support write access.
3227 ``V4L2_CID_BAND_STOP_FILTER (integer)``
3228 Switch the band-stop filter of a camera sensor on or off, or specify
3229 its strength. Such band-stop filters can be used, for example, to
3230 filter out the fluorescent light component.
3232 .. _v4l2-auto-n-preset-white-balance:
3234 ``V4L2_CID_AUTO_N_PRESET_WHITE_BALANCE``
3237 enum v4l2_auto_n_preset_white_balance -
3238 Sets white balance to automatic, manual or a preset. The presets
3239 determine color temperature of the light as a hint to the camera for
3240 white balance adjustments resulting in most accurate color
3241 representation. The following white balance presets are listed in
3242 order of increasing color temperature.
3244 .. tabularcolumns:: |p{7.0 cm}|p{10.5cm}|
3252 - ``V4L2_WHITE_BALANCE_MANUAL``
3254 - Manual white balance.
3258 - ``V4L2_WHITE_BALANCE_AUTO``
3260 - Automatic white balance adjustments.
3264 - ``V4L2_WHITE_BALANCE_INCANDESCENT``
3266 - White balance setting for incandescent (tungsten) lighting. It
3267 generally cools down the colors and corresponds approximately to
3268 2500...3500 K color temperature range.
3272 - ``V4L2_WHITE_BALANCE_FLUORESCENT``
3274 - White balance preset for fluorescent lighting. It corresponds
3275 approximately to 4000...5000 K color temperature.
3279 - ``V4L2_WHITE_BALANCE_FLUORESCENT_H``
3281 - With this setting the camera will compensate for fluorescent H
3286 - ``V4L2_WHITE_BALANCE_HORIZON``
3288 - White balance setting for horizon daylight. It corresponds
3289 approximately to 5000 K color temperature.
3293 - ``V4L2_WHITE_BALANCE_DAYLIGHT``
3295 - White balance preset for daylight (with clear sky). It corresponds
3296 approximately to 5000...6500 K color temperature.
3300 - ``V4L2_WHITE_BALANCE_FLASH``
3302 - With this setting the camera will compensate for the flash light.
3303 It slightly warms up the colors and corresponds roughly to
3304 5000...5500 K color temperature.
3308 - ``V4L2_WHITE_BALANCE_CLOUDY``
3310 - White balance preset for moderately overcast sky. This option
3311 corresponds approximately to 6500...8000 K color temperature
3316 - ``V4L2_WHITE_BALANCE_SHADE``
3318 - White balance preset for shade or heavily overcast sky. It
3319 corresponds approximately to 9000...10000 K color temperature.
3323 .. _v4l2-wide-dynamic-range:
3325 ``V4L2_CID_WIDE_DYNAMIC_RANGE (boolean)``
3326 Enables or disables the camera's wide dynamic range feature. This
3327 feature allows to obtain clear images in situations where intensity
3328 of the illumination varies significantly throughout the scene, i.e.
3329 there are simultaneously very dark and very bright areas. It is most
3330 commonly realized in cameras by combining two subsequent frames with
3331 different exposure times. [#f1]_
3333 .. _v4l2-image-stabilization:
3335 ``V4L2_CID_IMAGE_STABILIZATION (boolean)``
3336 Enables or disables image stabilization.
3338 ``V4L2_CID_ISO_SENSITIVITY (integer menu)``
3339 Determines ISO equivalent of an image sensor indicating the sensor's
3340 sensitivity to light. The numbers are expressed in arithmetic scale,
3341 as per :ref:`iso12232` standard, where doubling the sensor
3342 sensitivity is represented by doubling the numerical ISO value.
3343 Applications should interpret the values as standard ISO values
3344 multiplied by 1000, e.g. control value 800 stands for ISO 0.8.
3345 Drivers will usually support only a subset of standard ISO values.
3346 The effect of setting this control while the
3347 ``V4L2_CID_ISO_SENSITIVITY_AUTO`` control is set to a value other
3348 than ``V4L2_CID_ISO_SENSITIVITY_MANUAL`` is undefined, drivers
3349 should ignore such requests.
3351 .. _v4l2-iso-sensitivity-auto-type:
3353 ``V4L2_CID_ISO_SENSITIVITY_AUTO``
3356 enum v4l2_iso_sensitivity_type -
3357 Enables or disables automatic ISO sensitivity adjustments.
3368 - ``V4L2_CID_ISO_SENSITIVITY_MANUAL``
3370 - Manual ISO sensitivity.
3374 - ``V4L2_CID_ISO_SENSITIVITY_AUTO``
3376 - Automatic ISO sensitivity adjustments.
3380 .. _v4l2-scene-mode:
3382 ``V4L2_CID_SCENE_MODE``
3385 enum v4l2_scene_mode -
3386 This control allows to select scene programs as the camera automatic
3387 modes optimized for common shooting scenes. Within these modes the
3388 camera determines best exposure, aperture, focusing, light metering,
3389 white balance and equivalent sensitivity. The controls of those
3390 parameters are influenced by the scene mode control. An exact
3391 behavior in each mode is subject to the camera specification.
3393 When the scene mode feature is not used, this control should be set
3394 to ``V4L2_SCENE_MODE_NONE`` to make sure the other possibly related
3395 controls are accessible. The following scene programs are defined:
3397 .. tabularcolumns:: |p{6.0cm}|p{11.5cm}|
3405 - ``V4L2_SCENE_MODE_NONE``
3407 - The scene mode feature is disabled.
3411 - ``V4L2_SCENE_MODE_BACKLIGHT``
3413 - Backlight. Compensates for dark shadows when light is coming from
3414 behind a subject, also by automatically turning on the flash.
3418 - ``V4L2_SCENE_MODE_BEACH_SNOW``
3420 - Beach and snow. This mode compensates for all-white or bright
3421 scenes, which tend to look gray and low contrast, when camera's
3422 automatic exposure is based on an average scene brightness. To
3423 compensate, this mode automatically slightly overexposes the
3424 frames. The white balance may also be adjusted to compensate for
3425 the fact that reflected snow looks bluish rather than white.
3429 - ``V4L2_SCENE_MODE_CANDLELIGHT``
3431 - Candle light. The camera generally raises the ISO sensitivity and
3432 lowers the shutter speed. This mode compensates for relatively
3433 close subject in the scene. The flash is disabled in order to
3434 preserve the ambiance of the light.
3438 - ``V4L2_SCENE_MODE_DAWN_DUSK``
3440 - Dawn and dusk. Preserves the colors seen in low natural light
3441 before dusk and after down. The camera may turn off the flash, and
3442 automatically focus at infinity. It will usually boost saturation
3443 and lower the shutter speed.
3447 - ``V4L2_SCENE_MODE_FALL_COLORS``
3449 - Fall colors. Increases saturation and adjusts white balance for
3450 color enhancement. Pictures of autumn leaves get saturated reds
3455 - ``V4L2_SCENE_MODE_FIREWORKS``
3457 - Fireworks. Long exposure times are used to capture the expanding
3458 burst of light from a firework. The camera may invoke image
3463 - ``V4L2_SCENE_MODE_LANDSCAPE``
3465 - Landscape. The camera may choose a small aperture to provide deep
3466 depth of field and long exposure duration to help capture detail
3467 in dim light conditions. The focus is fixed at infinity. Suitable
3468 for distant and wide scenery.
3472 - ``V4L2_SCENE_MODE_NIGHT``
3474 - Night, also known as Night Landscape. Designed for low light
3475 conditions, it preserves detail in the dark areas without blowing
3476 out bright objects. The camera generally sets itself to a
3477 medium-to-high ISO sensitivity, with a relatively long exposure
3478 time, and turns flash off. As such, there will be increased image
3479 noise and the possibility of blurred image.
3483 - ``V4L2_SCENE_MODE_PARTY_INDOOR``
3485 - Party and indoor. Designed to capture indoor scenes that are lit
3486 by indoor background lighting as well as the flash. The camera
3487 usually increases ISO sensitivity, and adjusts exposure for the
3488 low light conditions.
3492 - ``V4L2_SCENE_MODE_PORTRAIT``
3494 - Portrait. The camera adjusts the aperture so that the depth of
3495 field is reduced, which helps to isolate the subject against a
3496 smooth background. Most cameras recognize the presence of faces in
3497 the scene and focus on them. The color hue is adjusted to enhance
3498 skin tones. The intensity of the flash is often reduced.
3502 - ``V4L2_SCENE_MODE_SPORTS``
3504 - Sports. Significantly increases ISO and uses a fast shutter speed
3505 to freeze motion of rapidly-moving subjects. Increased image noise
3506 may be seen in this mode.
3510 - ``V4L2_SCENE_MODE_SUNSET``
3512 - Sunset. Preserves deep hues seen in sunsets and sunrises. It bumps
3517 - ``V4L2_SCENE_MODE_TEXT``
3519 - Text. It applies extra contrast and sharpness, it is typically a
3520 black-and-white mode optimized for readability. Automatic focus
3521 may be switched to close-up mode and this setting may also involve
3522 some lens-distortion correction.
3526 ``V4L2_CID_3A_LOCK (bitmask)``
3527 This control locks or unlocks the automatic focus, exposure and
3528 white balance. The automatic adjustments can be paused independently
3529 by setting the corresponding lock bit to 1. The camera then retains
3530 the settings until the lock bit is cleared. The following lock bits
3533 When a given algorithm is not enabled, drivers should ignore
3534 requests to lock it and should return no error. An example might be
3535 an application setting bit ``V4L2_LOCK_WHITE_BALANCE`` when the
3536 ``V4L2_CID_AUTO_WHITE_BALANCE`` control is set to ``FALSE``. The
3537 value of this control may be changed by exposure, white balance or
3549 - ``V4L2_LOCK_EXPOSURE``
3551 - Automatic exposure adjustments lock.
3555 - ``V4L2_LOCK_WHITE_BALANCE``
3557 - Automatic white balance adjustments lock.
3561 - ``V4L2_LOCK_FOCUS``
3563 - Automatic focus lock.
3567 ``V4L2_CID_PAN_SPEED (integer)``
3568 This control turns the camera horizontally at the specific speed.
3569 The unit is undefined. A positive value moves the camera to the
3570 right (clockwise when viewed from above), a negative value to the
3571 left. A value of zero stops the motion if one is in progress and has
3572 no effect otherwise.
3574 ``V4L2_CID_TILT_SPEED (integer)``
3575 This control turns the camera vertically at the specified speed. The
3576 unit is undefined. A positive value moves the camera up, a negative
3577 value down. A value of zero stops the motion if one is in progress
3578 and has no effect otherwise.
3583 FM Transmitter Control Reference
3584 ================================
3586 The FM Transmitter (FM_TX) class includes controls for common features
3587 of FM transmissions capable devices. Currently this class includes
3588 parameters for audio compression, pilot tone generation, audio deviation
3589 limiter, RDS transmission and tuning power features.
3592 .. _fm-tx-control-id:
3597 ``V4L2_CID_FM_TX_CLASS (class)``
3598 The FM_TX class descriptor. Calling
3599 :ref:`VIDIOC_QUERYCTRL` for this control will
3600 return a description of this control class.
3602 ``V4L2_CID_RDS_TX_DEVIATION (integer)``
3603 Configures RDS signal frequency deviation level in Hz. The range and
3604 step are driver-specific.
3606 ``V4L2_CID_RDS_TX_PI (integer)``
3607 Sets the RDS Programme Identification field for transmission.
3609 ``V4L2_CID_RDS_TX_PTY (integer)``
3610 Sets the RDS Programme Type field for transmission. This encodes up
3611 to 31 pre-defined programme types.
3613 ``V4L2_CID_RDS_TX_PS_NAME (string)``
3614 Sets the Programme Service name (PS_NAME) for transmission. It is
3615 intended for static display on a receiver. It is the primary aid to
3616 listeners in programme service identification and selection. In
3617 Annex E of :ref:`iec62106`, the RDS specification, there is a full
3618 description of the correct character encoding for Programme Service
3619 name strings. Also from RDS specification, PS is usually a single
3620 eight character text. However, it is also possible to find receivers
3621 which can scroll strings sized as 8 x N characters. So, this control
3622 must be configured with steps of 8 characters. The result is it must
3623 always contain a string with size multiple of 8.
3625 ``V4L2_CID_RDS_TX_RADIO_TEXT (string)``
3626 Sets the Radio Text info for transmission. It is a textual
3627 description of what is being broadcasted. RDS Radio Text can be
3628 applied when broadcaster wishes to transmit longer PS names,
3629 programme-related information or any other text. In these cases,
3630 RadioText should be used in addition to ``V4L2_CID_RDS_TX_PS_NAME``.
3631 The encoding for Radio Text strings is also fully described in Annex
3632 E of :ref:`iec62106`. The length of Radio Text strings depends on
3633 which RDS Block is being used to transmit it, either 32 (2A block)
3634 or 64 (2B block). However, it is also possible to find receivers
3635 which can scroll strings sized as 32 x N or 64 x N characters. So,
3636 this control must be configured with steps of 32 or 64 characters.
3637 The result is it must always contain a string with size multiple of
3640 ``V4L2_CID_RDS_TX_MONO_STEREO (boolean)``
3641 Sets the Mono/Stereo bit of the Decoder Identification code. If set,
3642 then the audio was recorded as stereo.
3644 ``V4L2_CID_RDS_TX_ARTIFICIAL_HEAD (boolean)``
3646 `Artificial Head <http://en.wikipedia.org/wiki/Artificial_head>`__
3647 bit of the Decoder Identification code. If set, then the audio was
3648 recorded using an artificial head.
3650 ``V4L2_CID_RDS_TX_COMPRESSED (boolean)``
3651 Sets the Compressed bit of the Decoder Identification code. If set,
3652 then the audio is compressed.
3654 ``V4L2_CID_RDS_TX_DYNAMIC_PTY (boolean)``
3655 Sets the Dynamic PTY bit of the Decoder Identification code. If set,
3656 then the PTY code is dynamically switched.
3658 ``V4L2_CID_RDS_TX_TRAFFIC_ANNOUNCEMENT (boolean)``
3659 If set, then a traffic announcement is in progress.
3661 ``V4L2_CID_RDS_TX_TRAFFIC_PROGRAM (boolean)``
3662 If set, then the tuned programme carries traffic announcements.
3664 ``V4L2_CID_RDS_TX_MUSIC_SPEECH (boolean)``
3665 If set, then this channel broadcasts music. If cleared, then it
3666 broadcasts speech. If the transmitter doesn't make this distinction,
3667 then it should be set.
3669 ``V4L2_CID_RDS_TX_ALT_FREQS_ENABLE (boolean)``
3670 If set, then transmit alternate frequencies.
3672 ``V4L2_CID_RDS_TX_ALT_FREQS (__u32 array)``
3673 The alternate frequencies in kHz units. The RDS standard allows for
3674 up to 25 frequencies to be defined. Drivers may support fewer
3675 frequencies so check the array size.
3677 ``V4L2_CID_AUDIO_LIMITER_ENABLED (boolean)``
3678 Enables or disables the audio deviation limiter feature. The limiter
3679 is useful when trying to maximize the audio volume, minimize
3680 receiver-generated distortion and prevent overmodulation.
3682 ``V4L2_CID_AUDIO_LIMITER_RELEASE_TIME (integer)``
3683 Sets the audio deviation limiter feature release time. Unit is in
3684 useconds. Step and range are driver-specific.
3686 ``V4L2_CID_AUDIO_LIMITER_DEVIATION (integer)``
3687 Configures audio frequency deviation level in Hz. The range and step
3688 are driver-specific.
3690 ``V4L2_CID_AUDIO_COMPRESSION_ENABLED (boolean)``
3691 Enables or disables the audio compression feature. This feature
3692 amplifies signals below the threshold by a fixed gain and compresses
3693 audio signals above the threshold by the ratio of Threshold/(Gain +
3696 ``V4L2_CID_AUDIO_COMPRESSION_GAIN (integer)``
3697 Sets the gain for audio compression feature. It is a dB value. The
3698 range and step are driver-specific.
3700 ``V4L2_CID_AUDIO_COMPRESSION_THRESHOLD (integer)``
3701 Sets the threshold level for audio compression freature. It is a dB
3702 value. The range and step are driver-specific.
3704 ``V4L2_CID_AUDIO_COMPRESSION_ATTACK_TIME (integer)``
3705 Sets the attack time for audio compression feature. It is a useconds
3706 value. The range and step are driver-specific.
3708 ``V4L2_CID_AUDIO_COMPRESSION_RELEASE_TIME (integer)``
3709 Sets the release time for audio compression feature. It is a
3710 useconds value. The range and step are driver-specific.
3712 ``V4L2_CID_PILOT_TONE_ENABLED (boolean)``
3713 Enables or disables the pilot tone generation feature.
3715 ``V4L2_CID_PILOT_TONE_DEVIATION (integer)``
3716 Configures pilot tone frequency deviation level. Unit is in Hz. The
3717 range and step are driver-specific.
3719 ``V4L2_CID_PILOT_TONE_FREQUENCY (integer)``
3720 Configures pilot tone frequency value. Unit is in Hz. The range and
3721 step are driver-specific.
3723 ``V4L2_CID_TUNE_PREEMPHASIS``
3726 enum v4l2_preemphasis -
3727 Configures the pre-emphasis value for broadcasting. A pre-emphasis
3728 filter is applied to the broadcast to accentuate the high audio
3729 frequencies. Depending on the region, a time constant of either 50
3730 or 75 useconds is used. The enum v4l2_preemphasis defines possible
3731 values for pre-emphasis. Here they are:
3742 - ``V4L2_PREEMPHASIS_DISABLED``
3744 - No pre-emphasis is applied.
3748 - ``V4L2_PREEMPHASIS_50_uS``
3750 - A pre-emphasis of 50 uS is used.
3754 - ``V4L2_PREEMPHASIS_75_uS``
3756 - A pre-emphasis of 75 uS is used.
3760 ``V4L2_CID_TUNE_POWER_LEVEL (integer)``
3761 Sets the output power level for signal transmission. Unit is in
3762 dBuV. Range and step are driver-specific.
3764 ``V4L2_CID_TUNE_ANTENNA_CAPACITOR (integer)``
3765 This selects the value of antenna tuning capacitor manually or
3766 automatically if set to zero. Unit, range and step are
3769 For more details about RDS specification, refer to :ref:`iec62106`
3770 document, from CENELEC.
3775 Flash Control Reference
3776 =======================
3778 The V4L2 flash controls are intended to provide generic access to flash
3779 controller devices. Flash controller devices are typically used in
3782 The interface can support both LED and xenon flash devices. As of
3783 writing this, there is no xenon flash driver using this interface.
3786 .. _flash-controls-use-cases:
3792 Unsynchronised LED flash (software strobe)
3793 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3795 Unsynchronised LED flash is controlled directly by the host as the
3796 sensor. The flash must be enabled by the host before the exposure of the
3797 image starts and disabled once it ends. The host is fully responsible
3798 for the timing of the flash.
3800 Example of such device: Nokia N900.
3803 Synchronised LED flash (hardware strobe)
3804 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3806 The synchronised LED flash is pre-programmed by the host (power and
3807 timeout) but controlled by the sensor through a strobe signal from the
3808 sensor to the flash.
3810 The sensor controls the flash duration and timing. This information
3811 typically must be made available to the sensor.
3817 LED flash may be used as torch in conjunction with another use case
3818 involving camera or individually.
3821 .. _flash-control-id:
3826 ``V4L2_CID_FLASH_CLASS (class)``
3827 The FLASH class descriptor.
3829 ``V4L2_CID_FLASH_LED_MODE (menu)``
3830 Defines the mode of the flash LED, the high-power white LED attached
3831 to the flash controller. Setting this control may not be possible in
3832 presence of some faults. See V4L2_CID_FLASH_FAULT.
3843 - ``V4L2_FLASH_LED_MODE_NONE``
3849 - ``V4L2_FLASH_LED_MODE_FLASH``
3855 - ``V4L2_FLASH_LED_MODE_TORCH``
3857 - Torch mode. See V4L2_CID_FLASH_TORCH_INTENSITY.
3861 ``V4L2_CID_FLASH_STROBE_SOURCE (menu)``
3862 Defines the source of the flash LED strobe.
3864 .. tabularcolumns:: |p{7.0cm}|p{10.5cm}|
3872 - ``V4L2_FLASH_STROBE_SOURCE_SOFTWARE``
3874 - The flash strobe is triggered by using the
3875 V4L2_CID_FLASH_STROBE control.
3879 - ``V4L2_FLASH_STROBE_SOURCE_EXTERNAL``
3881 - The flash strobe is triggered by an external source. Typically
3882 this is a sensor, which makes it possible to synchronises the
3883 flash strobe start to exposure start.
3887 ``V4L2_CID_FLASH_STROBE (button)``
3888 Strobe flash. Valid when V4L2_CID_FLASH_LED_MODE is set to
3889 V4L2_FLASH_LED_MODE_FLASH and V4L2_CID_FLASH_STROBE_SOURCE
3890 is set to V4L2_FLASH_STROBE_SOURCE_SOFTWARE. Setting this
3891 control may not be possible in presence of some faults. See
3892 V4L2_CID_FLASH_FAULT.
3894 ``V4L2_CID_FLASH_STROBE_STOP (button)``
3895 Stop flash strobe immediately.
3897 ``V4L2_CID_FLASH_STROBE_STATUS (boolean)``
3898 Strobe status: whether the flash is strobing at the moment or not.
3899 This is a read-only control.
3901 ``V4L2_CID_FLASH_TIMEOUT (integer)``
3902 Hardware timeout for flash. The flash strobe is stopped after this
3903 period of time has passed from the start of the strobe.
3905 ``V4L2_CID_FLASH_INTENSITY (integer)``
3906 Intensity of the flash strobe when the flash LED is in flash mode
3907 (V4L2_FLASH_LED_MODE_FLASH). The unit should be milliamps (mA)
3910 ``V4L2_CID_FLASH_TORCH_INTENSITY (integer)``
3911 Intensity of the flash LED in torch mode
3912 (V4L2_FLASH_LED_MODE_TORCH). The unit should be milliamps (mA)
3913 if possible. Setting this control may not be possible in presence of
3914 some faults. See V4L2_CID_FLASH_FAULT.
3916 ``V4L2_CID_FLASH_INDICATOR_INTENSITY (integer)``
3917 Intensity of the indicator LED. The indicator LED may be fully
3918 independent of the flash LED. The unit should be microamps (uA) if
3921 ``V4L2_CID_FLASH_FAULT (bitmask)``
3922 Faults related to the flash. The faults tell about specific problems
3923 in the flash chip itself or the LEDs attached to it. Faults may
3924 prevent further use of some of the flash controls. In particular,
3925 V4L2_CID_FLASH_LED_MODE is set to V4L2_FLASH_LED_MODE_NONE
3926 if the fault affects the flash LED. Exactly which faults have such
3927 an effect is chip dependent. Reading the faults resets the control
3928 and returns the chip to a usable state if possible.
3930 .. tabularcolumns:: |p{8.0cm}|p{9.5cm}|
3939 - ``V4L2_FLASH_FAULT_OVER_VOLTAGE``
3941 - Flash controller voltage to the flash LED has exceeded the limit
3942 specific to the flash controller.
3946 - ``V4L2_FLASH_FAULT_TIMEOUT``
3948 - The flash strobe was still on when the timeout set by the user ---
3949 V4L2_CID_FLASH_TIMEOUT control --- has expired. Not all flash
3950 controllers may set this in all such conditions.
3954 - ``V4L2_FLASH_FAULT_OVER_TEMPERATURE``
3956 - The flash controller has overheated.
3960 - ``V4L2_FLASH_FAULT_SHORT_CIRCUIT``
3962 - The short circuit protection of the flash controller has been
3967 - ``V4L2_FLASH_FAULT_OVER_CURRENT``
3969 - Current in the LED power supply has exceeded the limit specific to
3970 the flash controller.
3974 - ``V4L2_FLASH_FAULT_INDICATOR``
3976 - The flash controller has detected a short or open circuit
3977 condition on the indicator LED.
3981 - ``V4L2_FLASH_FAULT_UNDER_VOLTAGE``
3983 - Flash controller voltage to the flash LED has been below the
3984 minimum limit specific to the flash controller.
3988 - ``V4L2_FLASH_FAULT_INPUT_VOLTAGE``
3990 - The input voltage of the flash controller is below the limit under
3991 which strobing the flash at full current will not be possible.The
3992 condition persists until this flag is no longer set.
3996 - ``V4L2_FLASH_FAULT_LED_OVER_TEMPERATURE``
3998 - The temperature of the LED has exceeded its allowed upper limit.
4002 ``V4L2_CID_FLASH_CHARGE (boolean)``
4003 Enable or disable charging of the xenon flash capacitor.
4005 ``V4L2_CID_FLASH_READY (boolean)``
4006 Is the flash ready to strobe? Xenon flashes require their capacitors
4007 charged before strobing. LED flashes often require a cooldown period
4008 after strobe during which another strobe will not be possible. This
4009 is a read-only control.
4014 JPEG Control Reference
4015 ======================
4017 The JPEG class includes controls for common features of JPEG encoders
4018 and decoders. Currently it includes features for codecs implementing
4019 progressive baseline DCT compression process with Huffman entrophy
4023 .. _jpeg-control-id:
4028 ``V4L2_CID_JPEG_CLASS (class)``
4029 The JPEG class descriptor. Calling
4030 :ref:`VIDIOC_QUERYCTRL` for this control will
4031 return a description of this control class.
4033 ``V4L2_CID_JPEG_CHROMA_SUBSAMPLING (menu)``
4034 The chroma subsampling factors describe how each component of an
4035 input image is sampled, in respect to maximum sample rate in each
4036 spatial dimension. See :ref:`itu-t81`, clause A.1.1. for more
4037 details. The ``V4L2_CID_JPEG_CHROMA_SUBSAMPLING`` control determines
4038 how Cb and Cr components are downsampled after coverting an input
4039 image from RGB to Y'CbCr color space.
4041 .. tabularcolumns:: |p{7.0cm}|p{10.5cm}|
4050 - ``V4L2_JPEG_CHROMA_SUBSAMPLING_444``
4052 - No chroma subsampling, each pixel has Y, Cr and Cb values.
4056 - ``V4L2_JPEG_CHROMA_SUBSAMPLING_422``
4058 - Horizontally subsample Cr, Cb components by a factor of 2.
4062 - ``V4L2_JPEG_CHROMA_SUBSAMPLING_420``
4064 - Subsample Cr, Cb components horizontally and vertically by 2.
4068 - ``V4L2_JPEG_CHROMA_SUBSAMPLING_411``
4070 - Horizontally subsample Cr, Cb components by a factor of 4.
4074 - ``V4L2_JPEG_CHROMA_SUBSAMPLING_410``
4076 - Subsample Cr, Cb components horizontally by 4 and vertically by 2.
4080 - ``V4L2_JPEG_CHROMA_SUBSAMPLING_GRAY``
4082 - Use only luminance component.
4086 ``V4L2_CID_JPEG_RESTART_INTERVAL (integer)``
4087 The restart interval determines an interval of inserting RSTm
4088 markers (m = 0..7). The purpose of these markers is to additionally
4089 reinitialize the encoder process, in order to process blocks of an
4090 image independently. For the lossy compression processes the restart
4091 interval unit is MCU (Minimum Coded Unit) and its value is contained
4092 in DRI (Define Restart Interval) marker. If
4093 ``V4L2_CID_JPEG_RESTART_INTERVAL`` control is set to 0, DRI and RSTm
4094 markers will not be inserted.
4096 .. _jpeg-quality-control:
4098 ``V4L2_CID_JPEG_COMPRESSION_QUALITY (integer)``
4099 ``V4L2_CID_JPEG_COMPRESSION_QUALITY`` control determines trade-off
4100 between image quality and size. It provides simpler method for
4101 applications to control image quality, without a need for direct
4102 reconfiguration of luminance and chrominance quantization tables. In
4103 cases where a driver uses quantization tables configured directly by
4104 an application, using interfaces defined elsewhere,
4105 ``V4L2_CID_JPEG_COMPRESSION_QUALITY`` control should be set by
4108 The value range of this control is driver-specific. Only positive,
4109 non-zero values are meaningful. The recommended range is 1 - 100,
4110 where larger values correspond to better image quality.
4112 .. _jpeg-active-marker-control:
4114 ``V4L2_CID_JPEG_ACTIVE_MARKER (bitmask)``
4115 Specify which JPEG markers are included in compressed stream. This
4116 control is valid only for encoders.
4127 - ``V4L2_JPEG_ACTIVE_MARKER_APP0``
4129 - Application data segment APP\ :sub:`0`.
4133 - ``V4L2_JPEG_ACTIVE_MARKER_APP1``
4135 - Application data segment APP\ :sub:`1`.
4139 - ``V4L2_JPEG_ACTIVE_MARKER_COM``
4145 - ``V4L2_JPEG_ACTIVE_MARKER_DQT``
4147 - Quantization tables segment.
4151 - ``V4L2_JPEG_ACTIVE_MARKER_DHT``
4153 - Huffman tables segment.
4157 For more details about JPEG specification, refer to :ref:`itu-t81`,
4158 :ref:`jfif`, :ref:`w3c-jpeg-jfif`.
4161 .. _image-source-controls:
4163 Image Source Control Reference
4164 ==============================
4166 The Image Source control class is intended for low-level control of
4167 image source devices such as image sensors. The devices feature an
4168 analogue to digital converter and a bus transmitter to transmit the
4169 image data out of the device.
4172 .. _image-source-control-id:
4174 Image Source Control IDs
4175 ------------------------
4177 ``V4L2_CID_IMAGE_SOURCE_CLASS (class)``
4178 The IMAGE_SOURCE class descriptor.
4180 ``V4L2_CID_VBLANK (integer)``
4181 Vertical blanking. The idle period after every frame during which no
4182 image data is produced. The unit of vertical blanking is a line.
4183 Every line has length of the image width plus horizontal blanking at
4184 the pixel rate defined by ``V4L2_CID_PIXEL_RATE`` control in the
4187 ``V4L2_CID_HBLANK (integer)``
4188 Horizontal blanking. The idle period after every line of image data
4189 during which no image data is produced. The unit of horizontal
4192 ``V4L2_CID_ANALOGUE_GAIN (integer)``
4193 Analogue gain is gain affecting all colour components in the pixel
4194 matrix. The gain operation is performed in the analogue domain
4195 before A/D conversion.
4197 ``V4L2_CID_TEST_PATTERN_RED (integer)``
4198 Test pattern red colour component.
4200 ``V4L2_CID_TEST_PATTERN_GREENR (integer)``
4201 Test pattern green (next to red) colour component.
4203 ``V4L2_CID_TEST_PATTERN_BLUE (integer)``
4204 Test pattern blue colour component.
4206 ``V4L2_CID_TEST_PATTERN_GREENB (integer)``
4207 Test pattern green (next to blue) colour component.
4210 .. _image-process-controls:
4212 Image Process Control Reference
4213 ===============================
4215 The Image Process control class is intended for low-level control of
4216 image processing functions. Unlike ``V4L2_CID_IMAGE_SOURCE_CLASS``, the
4217 controls in this class affect processing the image, and do not control
4221 .. _image-process-control-id:
4223 Image Process Control IDs
4224 -------------------------
4226 ``V4L2_CID_IMAGE_PROC_CLASS (class)``
4227 The IMAGE_PROC class descriptor.
4229 ``V4L2_CID_LINK_FREQ (integer menu)``
4230 Data bus frequency. Together with the media bus pixel code, bus type
4231 (clock cycles per sample), the data bus frequency defines the pixel
4232 rate (``V4L2_CID_PIXEL_RATE``) in the pixel array (or possibly
4233 elsewhere, if the device is not an image sensor). The frame rate can
4234 be calculated from the pixel clock, image width and height and
4235 horizontal and vertical blanking. While the pixel rate control may
4236 be defined elsewhere than in the subdev containing the pixel array,
4237 the frame rate cannot be obtained from that information. This is
4238 because only on the pixel array it can be assumed that the vertical
4239 and horizontal blanking information is exact: no other blanking is
4240 allowed in the pixel array. The selection of frame rate is performed
4241 by selecting the desired horizontal and vertical blanking. The unit
4242 of this control is Hz.
4244 ``V4L2_CID_PIXEL_RATE (64-bit integer)``
4245 Pixel rate in the source pads of the subdev. This control is
4246 read-only and its unit is pixels / second.
4248 ``V4L2_CID_TEST_PATTERN (menu)``
4249 Some capture/display/sensor devices have the capability to generate
4250 test pattern images. These hardware specific test patterns can be
4251 used to test if a device is working properly.
4256 Digital Video Control Reference
4257 ===============================
4259 The Digital Video control class is intended to control receivers and
4260 transmitters for `VGA <http://en.wikipedia.org/wiki/Vga>`__,
4261 `DVI <http://en.wikipedia.org/wiki/Digital_Visual_Interface>`__
4262 (Digital Visual Interface), HDMI (:ref:`hdmi`) and DisplayPort
4263 (:ref:`dp`). These controls are generally expected to be private to
4264 the receiver or transmitter subdevice that implements them, so they are
4265 only exposed on the ``/dev/v4l-subdev*`` device node.
4269 Note that these devices can have multiple input or output pads which are
4270 hooked up to e.g. HDMI connectors. Even though the subdevice will
4271 receive or transmit video from/to only one of those pads, the other pads
4272 can still be active when it comes to EDID (Extended Display
4273 Identification Data, :ref:`vesaedid`) and HDCP (High-bandwidth Digital
4274 Content Protection System, :ref:`hdcp`) processing, allowing the
4275 device to do the fairly slow EDID/HDCP handling in advance. This allows
4276 for quick switching between connectors.
4278 These pads appear in several of the controls in this section as
4279 bitmasks, one bit for each pad. Bit 0 corresponds to pad 0, bit 1 to pad
4280 1, etc. The maximum value of the control is the set of valid pads.
4285 Digital Video Control IDs
4286 -------------------------
4288 ``V4L2_CID_DV_CLASS (class)``
4289 The Digital Video class descriptor.
4291 ``V4L2_CID_DV_TX_HOTPLUG (bitmask)``
4292 Many connectors have a hotplug pin which is high if EDID information
4293 is available from the source. This control shows the state of the
4294 hotplug pin as seen by the transmitter. Each bit corresponds to an
4295 output pad on the transmitter. If an output pad does not have an
4296 associated hotplug pin, then the bit for that pad will be 0. This
4297 read-only control is applicable to DVI-D, HDMI and DisplayPort
4300 ``V4L2_CID_DV_TX_RXSENSE (bitmask)``
4301 Rx Sense is the detection of pull-ups on the TMDS clock lines. This
4302 normally means that the sink has left/entered standby (i.e. the
4303 transmitter can sense that the receiver is ready to receive video).
4304 Each bit corresponds to an output pad on the transmitter. If an
4305 output pad does not have an associated Rx Sense, then the bit for
4306 that pad will be 0. This read-only control is applicable to DVI-D
4309 ``V4L2_CID_DV_TX_EDID_PRESENT (bitmask)``
4310 When the transmitter sees the hotplug signal from the receiver it
4311 will attempt to read the EDID. If set, then the transmitter has read
4312 at least the first block (= 128 bytes). Each bit corresponds to an
4313 output pad on the transmitter. If an output pad does not support
4314 EDIDs, then the bit for that pad will be 0. This read-only control
4315 is applicable to VGA, DVI-A/D, HDMI and DisplayPort connectors.
4317 ``V4L2_CID_DV_TX_MODE``
4320 enum v4l2_dv_tx_mode -
4321 HDMI transmitters can transmit in DVI-D mode (just video) or in HDMI
4322 mode (video + audio + auxiliary data). This control selects which
4323 mode to use: V4L2_DV_TX_MODE_DVI_D or V4L2_DV_TX_MODE_HDMI.
4324 This control is applicable to HDMI connectors.
4326 ``V4L2_CID_DV_TX_RGB_RANGE``
4329 enum v4l2_dv_rgb_range -
4330 Select the quantization range for RGB output. V4L2_DV_RANGE_AUTO
4331 follows the RGB quantization range specified in the standard for the
4332 video interface (ie. :ref:`cea861` for HDMI).
4333 V4L2_DV_RANGE_LIMITED and V4L2_DV_RANGE_FULL override the
4334 standard to be compatible with sinks that have not implemented the
4335 standard correctly (unfortunately quite common for HDMI and DVI-D).
4336 Full range allows all possible values to be used whereas limited
4337 range sets the range to (16 << (N-8)) - (235 << (N-8)) where N is
4338 the number of bits per component. This control is applicable to VGA,
4339 DVI-A/D, HDMI and DisplayPort connectors.
4341 ``V4L2_CID_DV_TX_IT_CONTENT_TYPE``
4344 enum v4l2_dv_it_content_type -
4345 Configures the IT Content Type of the transmitted video. This
4346 information is sent over HDMI and DisplayPort connectors as part of
4347 the AVI InfoFrame. The term 'IT Content' is used for content that
4348 originates from a computer as opposed to content from a TV broadcast
4349 or an analog source. The enum v4l2_dv_it_content_type defines
4350 the possible content types:
4352 .. tabularcolumns:: |p{7.0cm}|p{10.5cm}|
4361 - ``V4L2_DV_IT_CONTENT_TYPE_GRAPHICS``
4363 - Graphics content. Pixel data should be passed unfiltered and
4364 without analog reconstruction.
4368 - ``V4L2_DV_IT_CONTENT_TYPE_PHOTO``
4370 - Photo content. The content is derived from digital still pictures.
4371 The content should be passed through with minimal scaling and
4372 picture enhancements.
4376 - ``V4L2_DV_IT_CONTENT_TYPE_CINEMA``
4382 - ``V4L2_DV_IT_CONTENT_TYPE_GAME``
4384 - Game content. Audio and video latency should be minimized.
4388 - ``V4L2_DV_IT_CONTENT_TYPE_NO_ITC``
4390 - No IT Content information is available and the ITC bit in the AVI
4391 InfoFrame is set to 0.
4395 ``V4L2_CID_DV_RX_POWER_PRESENT (bitmask)``
4396 Detects whether the receiver receives power from the source (e.g.
4397 HDMI carries 5V on one of the pins). This is often used to power an
4398 eeprom which contains EDID information, such that the source can
4399 read the EDID even if the sink is in standby/power off. Each bit
4400 corresponds to an input pad on the transmitter. If an input pad
4401 cannot detect whether power is present, then the bit for that pad
4402 will be 0. This read-only control is applicable to DVI-D, HDMI and
4403 DisplayPort connectors.
4405 ``V4L2_CID_DV_RX_RGB_RANGE``
4408 enum v4l2_dv_rgb_range -
4409 Select the quantization range for RGB input. V4L2_DV_RANGE_AUTO
4410 follows the RGB quantization range specified in the standard for the
4411 video interface (ie. :ref:`cea861` for HDMI).
4412 V4L2_DV_RANGE_LIMITED and V4L2_DV_RANGE_FULL override the
4413 standard to be compatible with sources that have not implemented the
4414 standard correctly (unfortunately quite common for HDMI and DVI-D).
4415 Full range allows all possible values to be used whereas limited
4416 range sets the range to (16 << (N-8)) - (235 << (N-8)) where N is
4417 the number of bits per component. This control is applicable to VGA,
4418 DVI-A/D, HDMI and DisplayPort connectors.
4420 ``V4L2_CID_DV_RX_IT_CONTENT_TYPE``
4423 enum v4l2_dv_it_content_type -
4424 Reads the IT Content Type of the received video. This information is
4425 sent over HDMI and DisplayPort connectors as part of the AVI
4426 InfoFrame. The term 'IT Content' is used for content that originates
4427 from a computer as opposed to content from a TV broadcast or an
4428 analog source. See ``V4L2_CID_DV_TX_IT_CONTENT_TYPE`` for the
4429 available content types.
4434 FM Receiver Control Reference
4435 =============================
4437 The FM Receiver (FM_RX) class includes controls for common features of
4438 FM Reception capable devices.
4441 .. _fm-rx-control-id:
4446 ``V4L2_CID_FM_RX_CLASS (class)``
4447 The FM_RX class descriptor. Calling
4448 :ref:`VIDIOC_QUERYCTRL` for this control will
4449 return a description of this control class.
4451 ``V4L2_CID_RDS_RECEPTION (boolean)``
4452 Enables/disables RDS reception by the radio tuner
4454 ``V4L2_CID_RDS_RX_PTY (integer)``
4455 Gets RDS Programme Type field. This encodes up to 31 pre-defined
4458 ``V4L2_CID_RDS_RX_PS_NAME (string)``
4459 Gets the Programme Service name (PS_NAME). It is intended for
4460 static display on a receiver. It is the primary aid to listeners in
4461 programme service identification and selection. In Annex E of
4462 :ref:`iec62106`, the RDS specification, there is a full
4463 description of the correct character encoding for Programme Service
4464 name strings. Also from RDS specification, PS is usually a single
4465 eight character text. However, it is also possible to find receivers
4466 which can scroll strings sized as 8 x N characters. So, this control
4467 must be configured with steps of 8 characters. The result is it must
4468 always contain a string with size multiple of 8.
4470 ``V4L2_CID_RDS_RX_RADIO_TEXT (string)``
4471 Gets the Radio Text info. It is a textual description of what is
4472 being broadcasted. RDS Radio Text can be applied when broadcaster
4473 wishes to transmit longer PS names, programme-related information or
4474 any other text. In these cases, RadioText can be used in addition to
4475 ``V4L2_CID_RDS_RX_PS_NAME``. The encoding for Radio Text strings is
4476 also fully described in Annex E of :ref:`iec62106`. The length of
4477 Radio Text strings depends on which RDS Block is being used to
4478 transmit it, either 32 (2A block) or 64 (2B block). However, it is
4479 also possible to find receivers which can scroll strings sized as 32
4480 x N or 64 x N characters. So, this control must be configured with
4481 steps of 32 or 64 characters. The result is it must always contain a
4482 string with size multiple of 32 or 64.
4484 ``V4L2_CID_RDS_RX_TRAFFIC_ANNOUNCEMENT (boolean)``
4485 If set, then a traffic announcement is in progress.
4487 ``V4L2_CID_RDS_RX_TRAFFIC_PROGRAM (boolean)``
4488 If set, then the tuned programme carries traffic announcements.
4490 ``V4L2_CID_RDS_RX_MUSIC_SPEECH (boolean)``
4491 If set, then this channel broadcasts music. If cleared, then it
4492 broadcasts speech. If the transmitter doesn't make this distinction,
4493 then it will be set.
4495 ``V4L2_CID_TUNE_DEEMPHASIS``
4498 enum v4l2_deemphasis -
4499 Configures the de-emphasis value for reception. A de-emphasis filter
4500 is applied to the broadcast to accentuate the high audio
4501 frequencies. Depending on the region, a time constant of either 50
4502 or 75 useconds is used. The enum v4l2_deemphasis defines possible
4503 values for de-emphasis. Here they are:
4514 - ``V4L2_DEEMPHASIS_DISABLED``
4516 - No de-emphasis is applied.
4520 - ``V4L2_DEEMPHASIS_50_uS``
4522 - A de-emphasis of 50 uS is used.
4526 - ``V4L2_DEEMPHASIS_75_uS``
4528 - A de-emphasis of 75 uS is used.
4533 .. _detect-controls:
4535 Detect Control Reference
4536 ========================
4538 The Detect class includes controls for common features of various motion
4539 or object detection capable devices.
4542 .. _detect-control-id:
4547 ``V4L2_CID_DETECT_CLASS (class)``
4548 The Detect class descriptor. Calling
4549 :ref:`VIDIOC_QUERYCTRL` for this control will
4550 return a description of this control class.
4552 ``V4L2_CID_DETECT_MD_MODE (menu)``
4553 Sets the motion detection mode.
4555 .. tabularcolumns:: |p{7.5cm}|p{10.0cm}|
4564 - ``V4L2_DETECT_MD_MODE_DISABLED``
4566 - Disable motion detection.
4570 - ``V4L2_DETECT_MD_MODE_GLOBAL``
4572 - Use a single motion detection threshold.
4576 - ``V4L2_DETECT_MD_MODE_THRESHOLD_GRID``
4578 - The image is divided into a grid, each cell with its own motion
4579 detection threshold. These thresholds are set through the
4580 ``V4L2_CID_DETECT_MD_THRESHOLD_GRID`` matrix control.
4584 - ``V4L2_DETECT_MD_MODE_REGION_GRID``
4586 - The image is divided into a grid, each cell with its own region
4587 value that specifies which per-region motion detection thresholds
4588 should be used. Each region has its own thresholds. How these
4589 per-region thresholds are set up is driver-specific. The region
4590 values for the grid are set through the
4591 ``V4L2_CID_DETECT_MD_REGION_GRID`` matrix control.
4595 ``V4L2_CID_DETECT_MD_GLOBAL_THRESHOLD (integer)``
4596 Sets the global motion detection threshold to be used with the
4597 ``V4L2_DETECT_MD_MODE_GLOBAL`` motion detection mode.
4599 ``V4L2_CID_DETECT_MD_THRESHOLD_GRID (__u16 matrix)``
4600 Sets the motion detection thresholds for each cell in the grid. To
4601 be used with the ``V4L2_DETECT_MD_MODE_THRESHOLD_GRID`` motion
4602 detection mode. Matrix element (0, 0) represents the cell at the
4603 top-left of the grid.
4605 ``V4L2_CID_DETECT_MD_REGION_GRID (__u8 matrix)``
4606 Sets the motion detection region value for each cell in the grid. To
4607 be used with the ``V4L2_DETECT_MD_MODE_REGION_GRID`` motion
4608 detection mode. Matrix element (0, 0) represents the cell at the
4609 top-left of the grid.
4612 .. _rf-tuner-controls:
4614 RF Tuner Control Reference
4615 ==========================
4617 The RF Tuner (RF_TUNER) class includes controls for common features of
4618 devices having RF tuner.
4620 In this context, RF tuner is radio receiver circuit between antenna and
4621 demodulator. It receives radio frequency (RF) from the antenna and
4622 converts that received signal to lower intermediate frequency (IF) or
4623 baseband frequency (BB). Tuners that could do baseband output are often
4624 called Zero-IF tuners. Older tuners were typically simple PLL tuners
4625 inside a metal box, whilst newer ones are highly integrated chips
4626 without a metal box "silicon tuners". These controls are mostly
4627 applicable for new feature rich silicon tuners, just because older
4628 tuners does not have much adjustable features.
4630 For more information about RF tuners see
4631 `Tuner (radio) <http://en.wikipedia.org/wiki/Tuner_%28radio%29>`__
4632 and `RF front end <http://en.wikipedia.org/wiki/RF_front_end>`__
4636 .. _rf-tuner-control-id:
4638 RF_TUNER Control IDs
4639 --------------------
4641 ``V4L2_CID_RF_TUNER_CLASS (class)``
4642 The RF_TUNER class descriptor. Calling
4643 :ref:`VIDIOC_QUERYCTRL` for this control will
4644 return a description of this control class.
4646 ``V4L2_CID_RF_TUNER_BANDWIDTH_AUTO (boolean)``
4647 Enables/disables tuner radio channel bandwidth configuration. In
4648 automatic mode bandwidth configuration is performed by the driver.
4650 ``V4L2_CID_RF_TUNER_BANDWIDTH (integer)``
4651 Filter(s) on tuner signal path are used to filter signal according
4652 to receiving party needs. Driver configures filters to fulfill
4653 desired bandwidth requirement. Used when
4654 V4L2_CID_RF_TUNER_BANDWIDTH_AUTO is not set. Unit is in Hz. The
4655 range and step are driver-specific.
4657 ``V4L2_CID_RF_TUNER_LNA_GAIN_AUTO (boolean)``
4658 Enables/disables LNA automatic gain control (AGC)
4660 ``V4L2_CID_RF_TUNER_MIXER_GAIN_AUTO (boolean)``
4661 Enables/disables mixer automatic gain control (AGC)
4663 ``V4L2_CID_RF_TUNER_IF_GAIN_AUTO (boolean)``
4664 Enables/disables IF automatic gain control (AGC)
4666 ``V4L2_CID_RF_TUNER_RF_GAIN (integer)``
4667 The RF amplifier is the very first amplifier on the receiver signal
4668 path, just right after the antenna input. The difference between the
4669 LNA gain and the RF gain in this document is that the LNA gain is
4670 integrated in the tuner chip while the RF gain is a separate chip.
4671 There may be both RF and LNA gain controls in the same device. The
4672 range and step are driver-specific.
4674 ``V4L2_CID_RF_TUNER_LNA_GAIN (integer)``
4675 LNA (low noise amplifier) gain is first gain stage on the RF tuner
4676 signal path. It is located very close to tuner antenna input. Used
4677 when ``V4L2_CID_RF_TUNER_LNA_GAIN_AUTO`` is not set. See
4678 ``V4L2_CID_RF_TUNER_RF_GAIN`` to understand how RF gain and LNA gain
4679 differs from the each others. The range and step are
4682 ``V4L2_CID_RF_TUNER_MIXER_GAIN (integer)``
4683 Mixer gain is second gain stage on the RF tuner signal path. It is
4684 located inside mixer block, where RF signal is down-converted by the
4685 mixer. Used when ``V4L2_CID_RF_TUNER_MIXER_GAIN_AUTO`` is not set.
4686 The range and step are driver-specific.
4688 ``V4L2_CID_RF_TUNER_IF_GAIN (integer)``
4689 IF gain is last gain stage on the RF tuner signal path. It is
4690 located on output of RF tuner. It controls signal level of
4691 intermediate frequency output or baseband output. Used when
4692 ``V4L2_CID_RF_TUNER_IF_GAIN_AUTO`` is not set. The range and step
4693 are driver-specific.
4695 ``V4L2_CID_RF_TUNER_PLL_LOCK (boolean)``
4696 Is synthesizer PLL locked? RF tuner is receiving given frequency
4697 when that control is set. This is a read-only control.
4700 This control may be changed to a menu control in the future, if more
4701 options are required.