1 .. -*- coding: utf-8; mode: rst -*-
5 ************************************
6 ioctl VIDIOC_G_TUNER, VIDIOC_S_TUNER
7 ************************************
12 VIDIOC_G_TUNER - VIDIOC_S_TUNER - Get or set tuner attributes
18 .. c:function:: int ioctl( int fd, VIDIOC_G_TUNER, struct v4l2_tuner *argp )
21 .. c:function:: int ioctl( int fd, VIDIOC_S_TUNER, const struct v4l2_tuner *argp )
29 File descriptor returned by :ref:`open() <func-open>`.
37 To query the attributes of a tuner applications initialize the ``index``
38 field and zero out the ``reserved`` array of a struct
39 :c:type:`v4l2_tuner` and call the ``VIDIOC_G_TUNER`` ioctl
40 with a pointer to this structure. Drivers fill the rest of the structure
41 or return an ``EINVAL`` error code when the index is out of bounds. To
42 enumerate all tuners applications shall begin at index zero,
43 incrementing by one until the driver returns ``EINVAL``.
45 Tuners have two writable properties, the audio mode and the radio
46 frequency. To change the audio mode, applications initialize the
47 ``index``, ``audmode`` and ``reserved`` fields and call the
48 ``VIDIOC_S_TUNER`` ioctl. This will *not* change the current tuner,
49 which is determined by the current video input. Drivers may choose a
50 different audio mode if the requested mode is invalid or unsupported.
51 Since this is a write-only ioctl, it does not return the actually
54 :ref:`SDR <sdr>` specific tuner types are ``V4L2_TUNER_SDR`` and
55 ``V4L2_TUNER_RF``. For SDR devices ``audmode`` field must be initialized
56 to zero. The term 'tuner' means SDR receiver in this context.
58 To change the radio frequency the
59 :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl is available.
62 .. tabularcolumns:: |p{1.3cm}|p{3.0cm}|p{6.6cm}|p{6.6cm}|
64 .. c:type:: v4l2_tuner
66 .. cssclass:: longtable
68 .. flat-table:: struct v4l2_tuner
79 - :cspan:`1` Identifies the tuner, set by the application.
89 Name of the tuner, a NUL-terminated ASCII string.
91 This information is intended for the user.
99 - :cspan:`1` Type of the tuner, see :c:type:`v4l2_tuner_type`.
109 Tuner capability flags, see :ref:`tuner-capability`. Audio flags
110 indicate the ability to decode audio subprograms. They will *not*
111 change, for example with the current video standard.
113 When the structure refers to a radio tuner the
114 ``V4L2_TUNER_CAP_LANG1``, ``V4L2_TUNER_CAP_LANG2`` and
115 ``V4L2_TUNER_CAP_NORM`` flags can't be used.
117 If multiple frequency bands are supported, then ``capability`` is
118 the union of all ``capability`` fields of each struct
119 :c:type:`v4l2_frequency_band`.
127 - :cspan:`1` The lowest tunable frequency in units of 62.5 kHz, or
128 if the ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in units
129 of 62.5 Hz, or if the ``capability`` flag ``V4L2_TUNER_CAP_1HZ``
130 is set, in units of 1 Hz. If multiple frequency bands are
131 supported, then ``rangelow`` is the lowest frequency of all the
140 - :cspan:`1` The highest tunable frequency in units of 62.5 kHz,
141 or if the ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in
142 units of 62.5 Hz, or if the ``capability`` flag
143 ``V4L2_TUNER_CAP_1HZ`` is set, in units of 1 Hz. If multiple
144 frequency bands are supported, then ``rangehigh`` is the highest
145 frequency of all the frequency bands.
155 Some tuners or audio decoders can determine the received audio
156 subprograms by analyzing audio carriers, pilot tones or other
157 indicators. To pass this information drivers set flags defined in
158 :ref:`tuner-rxsubchans` in this field. For example:
164 - ``V4L2_TUNER_SUB_MONO``
166 - receiving mono audio
174 - receiving stereo audio and a secondary audio program
182 - receiving mono or stereo audio, the hardware cannot distinguish
190 - receiving bilingual audio
196 - ``MONO | STEREO | LANG1 | LANG2``
198 - receiving mono, stereo or bilingual audio
206 When the ``V4L2_TUNER_CAP_STEREO``, ``_LANG1``, ``_LANG2`` or
207 ``_SAP`` flag is cleared in the ``capability`` field, the
208 corresponding ``V4L2_TUNER_SUB_`` flag must not be set here.
210 This field is valid only if this is the tuner of the current video
211 input, or when the structure refers to a radio tuner.
221 The selected audio mode, see :ref:`tuner-audmode` for valid
222 values. The audio mode does not affect audio subprogram detection,
223 and like a :ref:`control` it does not automatically
224 change unless the requested mode is invalid or unsupported. See
225 :ref:`tuner-matrix` for possible results when the selected and
226 received audio programs do not match.
228 Currently this is the only field of struct
229 struct :c:type:`v4l2_tuner` applications can change.
237 - :cspan:`1` The signal strength if known.
239 Ranging from 0 to 65535. Higher values indicate a better signal.
247 - :cspan:`1` Automatic frequency control.
249 When the ``afc`` value is negative, the frequency is too
250 low, when positive too high.
258 - :cspan:`1` Reserved for future extensions.
260 Drivers and applications must set the array to zero.
264 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
266 .. c:type:: v4l2_tuner_type
268 .. flat-table:: enum v4l2_tuner_type
276 - ``V4L2_TUNER_RADIO``
280 - Tuner supports radio
284 - ``V4L2_TUNER_ANALOG_TV``
288 - Tuner supports analog TV
296 - Tuner controls the A/D and/or D/A block of a
297 Sofware Digital Radio (SDR)
305 - Tuner controls the RF part of a Sofware Digital Radio (SDR)
308 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
310 .. _tuner-capability:
312 .. cssclass:: longtable
314 .. flat-table:: Tuner and Modulator Capability Flags
322 - ``V4L2_TUNER_CAP_LOW``
326 - When set, tuning frequencies are expressed in units of 62.5 Hz
331 - ``V4L2_TUNER_CAP_NORM``
335 - This is a multi-standard tuner; the video standard can or must be
336 switched. (B/G PAL tuners for example are typically not considered
337 multi-standard because the video standard is automatically
338 determined from the frequency band.) The set of supported video
339 standards is available from the struct
340 :c:type:`v4l2_input` pointing to this tuner, see the
341 description of ioctl :ref:`VIDIOC_ENUMINPUT`
342 for details. Only ``V4L2_TUNER_ANALOG_TV`` tuners can have this
347 - ``V4L2_TUNER_CAP_HWSEEK_BOUNDED``
351 - If set, then this tuner supports the hardware seek functionality
352 where the seek stops when it reaches the end of the frequency
357 - ``V4L2_TUNER_CAP_HWSEEK_WRAP``
361 - If set, then this tuner supports the hardware seek functionality
362 where the seek wraps around when it reaches the end of the
367 - ``V4L2_TUNER_CAP_STEREO``
371 - Stereo audio reception is supported.
375 - ``V4L2_TUNER_CAP_LANG1``
379 - Reception of the primary language of a bilingual audio program is
380 supported. Bilingual audio is a feature of two-channel systems,
381 transmitting the primary language monaural on the main audio
382 carrier and a secondary language monaural on a second carrier.
383 Only ``V4L2_TUNER_ANALOG_TV`` tuners can have this capability.
387 - ``V4L2_TUNER_CAP_LANG2``
391 - Reception of the secondary language of a bilingual audio program
392 is supported. Only ``V4L2_TUNER_ANALOG_TV`` tuners can have this
397 - ``V4L2_TUNER_CAP_SAP``
401 - Reception of a secondary audio program is supported. This is a
402 feature of the BTSC system which accompanies the NTSC video
403 standard. Two audio carriers are available for mono or stereo
404 transmissions of a primary language, and an independent third
405 carrier for a monaural secondary language. Only
406 ``V4L2_TUNER_ANALOG_TV`` tuners can have this capability.
410 The ``V4L2_TUNER_CAP_LANG2`` and ``V4L2_TUNER_CAP_SAP``
411 flags are synonyms. ``V4L2_TUNER_CAP_SAP`` applies when the tuner
412 supports the ``V4L2_STD_NTSC_M`` video standard.
416 - ``V4L2_TUNER_CAP_RDS``
420 - RDS capture is supported. This capability is only valid for radio
425 - ``V4L2_TUNER_CAP_RDS_BLOCK_IO``
429 - The RDS data is passed as unparsed RDS blocks.
433 - ``V4L2_TUNER_CAP_RDS_CONTROLS``
437 - The RDS data is parsed by the hardware and set via controls.
441 - ``V4L2_TUNER_CAP_FREQ_BANDS``
445 - The :ref:`VIDIOC_ENUM_FREQ_BANDS`
446 ioctl can be used to enumerate the available frequency bands.
450 - ``V4L2_TUNER_CAP_HWSEEK_PROG_LIM``
454 - The range to search when using the hardware seek functionality is
456 :ref:`VIDIOC_S_HW_FREQ_SEEK` for
461 - ``V4L2_TUNER_CAP_1HZ``
465 - When set, tuning frequencies are expressed in units of 1 Hz
470 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
472 .. _tuner-rxsubchans:
474 .. flat-table:: Tuner Audio Reception Flags
482 - ``V4L2_TUNER_SUB_MONO``
486 - The tuner receives a mono audio signal.
490 - ``V4L2_TUNER_SUB_STEREO``
494 - The tuner receives a stereo audio signal.
498 - ``V4L2_TUNER_SUB_LANG1``
502 - The tuner receives the primary language of a bilingual audio
503 signal. Drivers must clear this flag when the current video
504 standard is ``V4L2_STD_NTSC_M``.
508 - ``V4L2_TUNER_SUB_LANG2``
512 - The tuner receives the secondary language of a bilingual audio
513 signal (or a second audio program).
517 - ``V4L2_TUNER_SUB_SAP``
521 - The tuner receives a Second Audio Program.
525 The ``V4L2_TUNER_SUB_LANG2`` and ``V4L2_TUNER_SUB_SAP``
526 flags are synonyms. The ``V4L2_TUNER_SUB_SAP`` flag applies
527 when the current video standard is ``V4L2_STD_NTSC_M``.
531 - ``V4L2_TUNER_SUB_RDS``
535 - The tuner receives an RDS channel.
539 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
543 .. flat-table:: Tuner Audio Modes
551 - ``V4L2_TUNER_MODE_MONO``
555 - Play mono audio. When the tuner receives a stereo signal this a
556 down-mix of the left and right channel. When the tuner receives a
557 bilingual or SAP signal this mode selects the primary language.
561 - ``V4L2_TUNER_MODE_STEREO``
565 - Play stereo audio. When the tuner receives bilingual audio it may
566 play different languages on the left and right channel or the
567 primary language is played on both channels.
569 Playing different languages in this mode is deprecated. New
570 drivers should do this only in ``MODE_LANG1_LANG2``.
572 When the tuner receives no stereo signal or does not support
573 stereo reception the driver shall fall back to ``MODE_MONO``.
577 - ``V4L2_TUNER_MODE_LANG1``
581 - Play the primary language, mono or stereo. Only
582 ``V4L2_TUNER_ANALOG_TV`` tuners support this mode.
586 - ``V4L2_TUNER_MODE_LANG2``
590 - Play the secondary language, mono. When the tuner receives no
591 bilingual audio or SAP, or their reception is not supported the
592 driver shall fall back to mono or stereo mode. Only
593 ``V4L2_TUNER_ANALOG_TV`` tuners support this mode.
597 - ``V4L2_TUNER_MODE_SAP``
601 - Play the Second Audio Program. When the tuner receives no
602 bilingual audio or SAP, or their reception is not supported the
603 driver shall fall back to mono or stereo mode. Only
604 ``V4L2_TUNER_ANALOG_TV`` tuners support this mode.
606 .. note:: The ``V4L2_TUNER_MODE_LANG2`` and ``V4L2_TUNER_MODE_SAP``
611 - ``V4L2_TUNER_MODE_LANG1_LANG2``
615 - Play the primary language on the left channel, the secondary
616 language on the right channel. When the tuner receives no
617 bilingual audio or SAP, it shall fall back to ``MODE_LANG1`` or
618 ``MODE_MONO``. Only ``V4L2_TUNER_ANALOG_TV`` tuners support this
623 \begin{adjustbox}{width=\columnwidth}
627 .. flat-table:: Tuner Audio Matrix
635 - :cspan:`5` Selected ``V4L2_TUNER_MODE_``
639 - Received ``V4L2_TUNER_SUB_``
649 - ``LANG1_LANG2``\ [#f1]_
677 - Mono/SAP (preferred) or Mono/Mono
687 - Stereo L/R (preferred) or Mono L+R
689 - Stereo L/R (preferred) or Mono L+R
691 - L/R (preferred) or L+R/L+R
701 - Stereo L/R (preferred) or Mono L+R
705 - L+R/SAP (preferred) or L/R or L+R/L+R
713 - Lang1/Lang2 (deprecated [#f2]_) or Lang1/Lang1
719 - Lang1/Lang2 (preferred) or Lang1/Lang1
723 \end{adjustbox}\newline\newline
728 On success 0 is returned, on error -1 and the ``errno`` variable is set
729 appropriately. The generic error codes are described at the
730 :ref:`Generic Error Codes <gen-errors>` chapter.
733 The struct :c:type:`v4l2_tuner` ``index`` is out of
737 This mode has been added in Linux 2.6.17 and may not be supported by
741 Playback of both languages in ``MODE_STEREO`` is deprecated. In the
742 future drivers should produce only the primary language in this mode.
743 Applications should request ``MODE_LANG1_LANG2`` to record both
744 languages or a stereo signal.