1.. Permission is granted to copy, distribute and/or modify this
2.. document under the terms of the GNU Free Documentation License,
3.. Version 1.1 or any later version published by the Free Software
4.. Foundation, with no Invariant Sections, no Front-Cover Texts
5.. and no Back-Cover Texts. A copy of the license is included at
6.. Documentation/userspace-api/media/fdl-appendix.rst.
7..
8.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
9
10.. _VIDIOC_G_AUDIO:
11
12************************************
13ioctl VIDIOC_G_AUDIO, VIDIOC_S_AUDIO
14************************************
15
16Name
17====
18
19VIDIOC_G_AUDIO - VIDIOC_S_AUDIO - Query or select the current audio input and its attributes
20
21
22Synopsis
23========
24
25.. c:function:: int ioctl( int fd, VIDIOC_G_AUDIO, struct v4l2_audio *argp )
26    :name: VIDIOC_G_AUDIO
27
28.. c:function:: int ioctl( int fd, VIDIOC_S_AUDIO, const struct v4l2_audio *argp )
29    :name: VIDIOC_S_AUDIO
30
31
32Arguments
33=========
34
35``fd``
36    File descriptor returned by :ref:`open() <func-open>`.
37
38``argp``
39    Pointer to struct :c:type:`v4l2_audio`.
40
41
42Description
43===========
44
45To query the current audio input applications zero out the ``reserved``
46array of a struct :c:type:`v4l2_audio` and call the
47:ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` ioctl with a pointer to this structure. Drivers fill
48the rest of the structure or return an ``EINVAL`` error code when the device
49has no audio inputs, or none which combine with the current video input.
50
51Audio inputs have one writable property, the audio mode. To select the
52current audio input *and* change the audio mode, applications initialize
53the ``index`` and ``mode`` fields, and the ``reserved`` array of a
54struct :c:type:`v4l2_audio` structure and call the :ref:`VIDIOC_S_AUDIO <VIDIOC_G_AUDIO>`
55ioctl. Drivers may switch to a different audio mode if the request
56cannot be satisfied. However, this is a write-only ioctl, it does not
57return the actual new audio mode.
58
59
60.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
61
62.. c:type:: v4l2_audio
63
64.. flat-table:: struct v4l2_audio
65    :header-rows:  0
66    :stub-columns: 0
67    :widths:       1 1 2
68
69    * - __u32
70      - ``index``
71      - Identifies the audio input, set by the driver or application.
72    * - __u8
73      - ``name``\ [32]
74      - Name of the audio input, a NUL-terminated ASCII string, for
75	example: "Line In". This information is intended for the user,
76	preferably the connector label on the device itself.
77    * - __u32
78      - ``capability``
79      - Audio capability flags, see :ref:`audio-capability`.
80    * - __u32
81      - ``mode``
82      - Audio mode flags set by drivers and applications (on
83	:ref:`VIDIOC_S_AUDIO <VIDIOC_G_AUDIO>` ioctl), see :ref:`audio-mode`.
84    * - __u32
85      - ``reserved``\ [2]
86      - Reserved for future extensions. Drivers and applications must set
87	the array to zero.
88
89
90
91.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
92
93.. _audio-capability:
94
95.. flat-table:: Audio Capability Flags
96    :header-rows:  0
97    :stub-columns: 0
98    :widths:       3 1 4
99
100    * - ``V4L2_AUDCAP_STEREO``
101      - 0x00001
102      - This is a stereo input. The flag is intended to automatically
103	disable stereo recording etc. when the signal is always monaural.
104	The API provides no means to detect if stereo is *received*,
105	unless the audio input belongs to a tuner.
106    * - ``V4L2_AUDCAP_AVL``
107      - 0x00002
108      - Automatic Volume Level mode is supported.
109
110
111
112.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
113
114.. _audio-mode:
115
116.. flat-table:: Audio Mode Flags
117    :header-rows:  0
118    :stub-columns: 0
119    :widths:       3 1 4
120
121    * - ``V4L2_AUDMODE_AVL``
122      - 0x00001
123      - AVL mode is on.
124
125
126Return Value
127============
128
129On success 0 is returned, on error -1 and the ``errno`` variable is set
130appropriately. The generic error codes are described at the
131:ref:`Generic Error Codes <gen-errors>` chapter.
132
133EINVAL
134    No audio inputs combine with the current video input, or the number
135    of the selected audio input is out of bounds or it does not combine.
136