0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002 .. c:namespace:: V4L
0003
0004 .. _VIDIOC_G_AUDIO:
0005
0006 ************************************
0007 ioctl VIDIOC_G_AUDIO, VIDIOC_S_AUDIO
0008 ************************************
0009
0010 Name
0011 ====
0012
0013 VIDIOC_G_AUDIO - VIDIOC_S_AUDIO - Query or select the current audio input and its attributes
0014
0015 Synopsis
0016 ========
0017
0018 .. c:macro:: VIDIOC_G_AUDIO
0019
0020 ``int ioctl(int fd, VIDIOC_G_AUDIO, struct v4l2_audio *argp)``
0021
0022 .. c:macro:: VIDIOC_S_AUDIO
0023
0024 ``int ioctl(int fd, VIDIOC_S_AUDIO, const struct v4l2_audio *argp)``
0025
0026 Arguments
0027 =========
0028
0029 ``fd``
0030 File descriptor returned by :c:func:`open()`.
0031
0032 ``argp``
0033 Pointer to struct :c:type:`v4l2_audio`.
0034
0035 Description
0036 ===========
0037
0038 To query the current audio input applications zero out the ``reserved``
0039 array of a struct :c:type:`v4l2_audio` and call the
0040 :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` ioctl with a pointer to this structure. Drivers fill
0041 the rest of the structure or return an ``EINVAL`` error code when the device
0042 has no audio inputs, or none which combine with the current video input.
0043
0044 Audio inputs have one writable property, the audio mode. To select the
0045 current audio input *and* change the audio mode, applications initialize
0046 the ``index`` and ``mode`` fields, and the ``reserved`` array of a
0047 struct :c:type:`v4l2_audio` structure and call the :ref:`VIDIOC_S_AUDIO <VIDIOC_G_AUDIO>`
0048 ioctl. Drivers may switch to a different audio mode if the request
0049 cannot be satisfied. However, this is a write-only ioctl, it does not
0050 return the actual new audio mode.
0051
0052 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
0053
0054 .. c:type:: v4l2_audio
0055
0056 .. flat-table:: struct v4l2_audio
0057 :header-rows: 0
0058 :stub-columns: 0
0059 :widths: 1 1 2
0060
0061 * - __u32
0062 - ``index``
0063 - Identifies the audio input, set by the driver or application.
0064 * - __u8
0065 - ``name``\ [32]
0066 - Name of the audio input, a NUL-terminated ASCII string, for
0067 example: "Line In". This information is intended for the user,
0068 preferably the connector label on the device itself.
0069 * - __u32
0070 - ``capability``
0071 - Audio capability flags, see :ref:`audio-capability`.
0072 * - __u32
0073 - ``mode``
0074 - Audio mode flags set by drivers and applications (on
0075 :ref:`VIDIOC_S_AUDIO <VIDIOC_G_AUDIO>` ioctl), see :ref:`audio-mode`.
0076 * - __u32
0077 - ``reserved``\ [2]
0078 - Reserved for future extensions. Drivers and applications must set
0079 the array to zero.
0080
0081
0082 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}|
0083
0084 .. _audio-capability:
0085
0086 .. flat-table:: Audio Capability Flags
0087 :header-rows: 0
0088 :stub-columns: 0
0089 :widths: 3 1 4
0090
0091 * - ``V4L2_AUDCAP_STEREO``
0092 - 0x00001
0093 - This is a stereo input. The flag is intended to automatically
0094 disable stereo recording etc. when the signal is always monaural.
0095 The API provides no means to detect if stereo is *received*,
0096 unless the audio input belongs to a tuner.
0097 * - ``V4L2_AUDCAP_AVL``
0098 - 0x00002
0099 - Automatic Volume Level mode is supported.
0100
0101
0102 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}|
0103
0104 .. _audio-mode:
0105
0106 .. flat-table:: Audio Mode Flags
0107 :header-rows: 0
0108 :stub-columns: 0
0109 :widths: 3 1 4
0110
0111 * - ``V4L2_AUDMODE_AVL``
0112 - 0x00001
0113 - AVL mode is on.
0114
0115 Return Value
0116 ============
0117
0118 On success 0 is returned, on error -1 and the ``errno`` variable is set
0119 appropriately. The generic error codes are described at the
0120 :ref:`Generic Error Codes <gen-errors>` chapter.
0121
0122 EINVAL
0123 No audio inputs combine with the current video input, or the number
0124 of the selected audio input is out of bounds or it does not combine.
