1<refentry id="vidioc-g-audio">
2  <refmeta>
3    <refentrytitle>ioctl VIDIOC_G_AUDIO, VIDIOC_S_AUDIO</refentrytitle>
4    &manvol;
5  </refmeta>
6
7  <refnamediv>
8    <refname>VIDIOC_G_AUDIO</refname>
9    <refname>VIDIOC_S_AUDIO</refname>
10    <refpurpose>Query or select the current audio input and its
11attributes</refpurpose>
12  </refnamediv>
13
14  <refsynopsisdiv>
15    <funcsynopsis>
16      <funcprototype>
17	<funcdef>int <function>ioctl</function></funcdef>
18	<paramdef>int <parameter>fd</parameter></paramdef>
19	<paramdef>int <parameter>request</parameter></paramdef>
20	<paramdef>struct v4l2_audio *<parameter>argp</parameter></paramdef>
21      </funcprototype>
22    </funcsynopsis>
23    <funcsynopsis>
24      <funcprototype>
25	<funcdef>int <function>ioctl</function></funcdef>
26	<paramdef>int <parameter>fd</parameter></paramdef>
27	<paramdef>int <parameter>request</parameter></paramdef>
28	<paramdef>const struct v4l2_audio *<parameter>argp</parameter></paramdef>
29      </funcprototype>
30    </funcsynopsis>
31  </refsynopsisdiv>
32
33  <refsect1>
34    <title>Arguments</title>
35
36    <variablelist>
37      <varlistentry>
38	<term><parameter>fd</parameter></term>
39	<listitem>
40	  <para>&fd;</para>
41	</listitem>
42      </varlistentry>
43      <varlistentry>
44	<term><parameter>request</parameter></term>
45	<listitem>
46	  <para>VIDIOC_G_AUDIO, VIDIOC_S_AUDIO</para>
47	</listitem>
48      </varlistentry>
49      <varlistentry>
50	<term><parameter>argp</parameter></term>
51	<listitem>
52	  <para></para>
53	</listitem>
54      </varlistentry>
55    </variablelist>
56  </refsect1>
57
58  <refsect1>
59    <title>Description</title>
60
61    <para>To query the current audio input applications zero out the
62<structfield>reserved</structfield> array of a &v4l2-audio;
63and call the <constant>VIDIOC_G_AUDIO</constant> ioctl with a pointer
64to this structure. Drivers fill the rest of the structure or return an
65&EINVAL; when the device has no audio inputs, or none which combine
66with the current video input.</para>
67
68    <para>Audio inputs have one writable property, the audio mode. To
69select the current audio input <emphasis>and</emphasis> change the
70audio mode, applications initialize the
71<structfield>index</structfield> and <structfield>mode</structfield>
72fields, and the
73<structfield>reserved</structfield> array of a
74<structname>v4l2_audio</structname> structure and call the
75<constant>VIDIOC_S_AUDIO</constant> ioctl. Drivers may switch to a
76different audio mode if the request cannot be satisfied. However, this
77is a write-only ioctl, it does not return the actual new audio
78mode.</para>
79
80    <table pgwide="1" frame="none" id="v4l2-audio">
81      <title>struct <structname>v4l2_audio</structname></title>
82      <tgroup cols="3">
83	&cs-str;
84	<tbody valign="top">
85	  <row>
86	    <entry>__u32</entry>
87	    <entry><structfield>index</structfield></entry>
88	    <entry>Identifies the audio input, set by the
89driver or application.</entry>
90	  </row>
91	  <row>
92	    <entry>__u8</entry>
93	    <entry><structfield>name</structfield>[32]</entry>
94	    <entry>Name of the audio input, a NUL-terminated ASCII
95string, for example: "Line In". This information is intended for the
96user, preferably the connector label on the device itself.</entry>
97	  </row>
98	  <row>
99	    <entry>__u32</entry>
100	    <entry><structfield>capability</structfield></entry>
101	    <entry>Audio capability flags, see <xref
102		linkend="audio-capability" />.</entry>
103	  </row>
104	  <row>
105	    <entry>__u32</entry>
106	    <entry><structfield>mode</structfield></entry>
107	    <entry>Audio mode flags set by drivers and applications (on
108	    <constant>VIDIOC_S_AUDIO</constant> ioctl), see <xref linkend="audio-mode" />.</entry>
109	  </row>
110	  <row>
111	    <entry>__u32</entry>
112	    <entry><structfield>reserved</structfield>[2]</entry>
113	    <entry>Reserved for future extensions. Drivers and
114applications must set the array to zero.</entry>
115	  </row>
116	</tbody>
117      </tgroup>
118    </table>
119
120    <table pgwide="1" frame="none" id="audio-capability">
121      <title>Audio Capability Flags</title>
122      <tgroup cols="3">
123	&cs-def;
124	<tbody valign="top">
125	  <row>
126	    <entry><constant>V4L2_AUDCAP_STEREO</constant></entry>
127	    <entry>0x00001</entry>
128	    <entry>This is a stereo input. The flag is intended to
129automatically disable stereo recording etc. when the signal is always
130monaural. The API provides no means to detect if stereo is
131<emphasis>received</emphasis>, unless the audio input belongs to a
132tuner.</entry>
133	  </row>
134	  <row>
135	    <entry><constant>V4L2_AUDCAP_AVL</constant></entry>
136	    <entry>0x00002</entry>
137	    <entry>Automatic Volume Level mode is supported.</entry>
138	  </row>
139	</tbody>
140      </tgroup>
141    </table>
142
143    <table pgwide="1" frame="none" id="audio-mode">
144      <title>Audio Mode Flags</title>
145      <tgroup cols="3">
146	&cs-def;
147	<tbody valign="top">
148	  <row>
149	    <entry><constant>V4L2_AUDMODE_AVL</constant></entry>
150	    <entry>0x00001</entry>
151	    <entry>AVL mode is on.</entry>
152	  </row>
153	</tbody>
154      </tgroup>
155    </table>
156  </refsect1>
157
158  <refsect1>
159    &return-value;
160
161    <variablelist>
162      <varlistentry>
163	<term><errorcode>EINVAL</errorcode></term>
164	<listitem>
165	  <para>No audio inputs combine with the current video input,
166or the number of the selected audio input is out of bounds or it does
167not combine.</para>
168	</listitem>
169      </varlistentry>
170    </variablelist>
171  </refsect1>
172</refentry>
173