1 .. SPDX-License-Identifier: GFDL-1.1-no-invari 1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2 2
3 .. _audio: 3 .. _audio:
4 4
5 ************************ 5 ************************
6 Audio Inputs and Outputs 6 Audio Inputs and Outputs
7 ************************ 7 ************************
8 8
9 Audio inputs and outputs are physical connecto 9 Audio inputs and outputs are physical connectors of a device. Video
10 capture devices have inputs, output devices ha 10 capture devices have inputs, output devices have outputs, zero or more
11 each. Radio devices have no audio inputs or ou 11 each. Radio devices have no audio inputs or outputs. They have exactly
12 one tuner which in fact *is* an audio source, 12 one tuner which in fact *is* an audio source, but this API associates
13 tuners with video inputs or outputs only, and 13 tuners with video inputs or outputs only, and radio devices have none of
14 these. [#f1]_ A connector on a TV card to loop 14 these. [#f1]_ A connector on a TV card to loop back the received audio
15 signal to a sound card is not considered an au 15 signal to a sound card is not considered an audio output.
16 16
17 Audio and video inputs and outputs are associa 17 Audio and video inputs and outputs are associated. Selecting a video
18 source also selects an audio source. This is m 18 source also selects an audio source. This is most evident when the video
19 and audio source is a tuner. Further audio con 19 and audio source is a tuner. Further audio connectors can combine with
20 more than one video input or output. Assumed t 20 more than one video input or output. Assumed two composite video inputs
21 and two audio inputs exist, there may be up to 21 and two audio inputs exist, there may be up to four valid combinations.
22 The relation of video and audio connectors is 22 The relation of video and audio connectors is defined in the
23 ``audioset`` field of the respective struct 23 ``audioset`` field of the respective struct
24 :c:type:`v4l2_input` or struct 24 :c:type:`v4l2_input` or struct
25 :c:type:`v4l2_output`, where each bit represen 25 :c:type:`v4l2_output`, where each bit represents the index
26 number, starting at zero, of one audio input o 26 number, starting at zero, of one audio input or output.
27 27
28 To learn about the number and attributes of th 28 To learn about the number and attributes of the available inputs and
29 outputs applications can enumerate them with t 29 outputs applications can enumerate them with the
30 :ref:`VIDIOC_ENUMAUDIO` and 30 :ref:`VIDIOC_ENUMAUDIO` and
31 :ref:`VIDIOC_ENUMAUDOUT <VIDIOC_ENUMAUDOUT>` i 31 :ref:`VIDIOC_ENUMAUDOUT <VIDIOC_ENUMAUDOUT>` ioctl, respectively.
32 The struct :c:type:`v4l2_audio` returned by th 32 The struct :c:type:`v4l2_audio` returned by the
33 :ref:`VIDIOC_ENUMAUDIO` ioctl also contains si 33 :ref:`VIDIOC_ENUMAUDIO` ioctl also contains signal
34 status information applicable when the current 34 status information applicable when the current audio input is queried.
35 35
36 The :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` and 36 The :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` and
37 :ref:`VIDIOC_G_AUDOUT <VIDIOC_G_AUDOUT>` ioctl 37 :ref:`VIDIOC_G_AUDOUT <VIDIOC_G_AUDOUT>` ioctls report the current
38 audio input and output, respectively. 38 audio input and output, respectively.
39 39
40 .. note:: 40 .. note::
41 41
42 Note that, unlike :ref:`VIDIOC_G_INPUT <VID 42 Note that, unlike :ref:`VIDIOC_G_INPUT <VIDIOC_G_INPUT>` and
43 :ref:`VIDIOC_G_OUTPUT <VIDIOC_G_OUTPUT>` th 43 :ref:`VIDIOC_G_OUTPUT <VIDIOC_G_OUTPUT>` these ioctls return a
44 structure as :ref:`VIDIOC_ENUMAUDIO` and 44 structure as :ref:`VIDIOC_ENUMAUDIO` and
45 :ref:`VIDIOC_ENUMAUDOUT <VIDIOC_ENUMAUDOUT> 45 :ref:`VIDIOC_ENUMAUDOUT <VIDIOC_ENUMAUDOUT>` do, not just an index.
46 46
47 To select an audio input and change its proper 47 To select an audio input and change its properties applications call the
48 :ref:`VIDIOC_S_AUDIO <VIDIOC_G_AUDIO>` ioctl. 48 :ref:`VIDIOC_S_AUDIO <VIDIOC_G_AUDIO>` ioctl. To select an audio
49 output (which presently has no changeable prop 49 output (which presently has no changeable properties) applications call
50 the :ref:`VIDIOC_S_AUDOUT <VIDIOC_G_AUDOUT>` i 50 the :ref:`VIDIOC_S_AUDOUT <VIDIOC_G_AUDOUT>` ioctl.
51 51
52 Drivers must implement all audio input ioctls 52 Drivers must implement all audio input ioctls when the device has
53 multiple selectable audio inputs, all audio ou 53 multiple selectable audio inputs, all audio output ioctls when the
54 device has multiple selectable audio outputs. 54 device has multiple selectable audio outputs. When the device has any
55 audio inputs or outputs the driver must set th 55 audio inputs or outputs the driver must set the ``V4L2_CAP_AUDIO`` flag
56 in the struct :c:type:`v4l2_capability` return 56 in the struct :c:type:`v4l2_capability` returned by
57 the :ref:`VIDIOC_QUERYCAP` ioctl. 57 the :ref:`VIDIOC_QUERYCAP` ioctl.
58 58
59 59
60 Example: Information about the current audio i 60 Example: Information about the current audio input
61 ============================================== 61 ==================================================
62 62
63 .. code-block:: c 63 .. code-block:: c
64 64
65 struct v4l2_audio audio; 65 struct v4l2_audio audio;
66 66
67 memset(&audio, 0, sizeof(audio)); 67 memset(&audio, 0, sizeof(audio));
68 68
69 if (-1 == ioctl(fd, VIDIOC_G_AUDIO, &audio 69 if (-1 == ioctl(fd, VIDIOC_G_AUDIO, &audio)) {
70 perror("VIDIOC_G_AUDIO"); 70 perror("VIDIOC_G_AUDIO");
71 exit(EXIT_FAILURE); 71 exit(EXIT_FAILURE);
72 } 72 }
73 73
74 printf("Current input: %s\\n", audio.name) 74 printf("Current input: %s\\n", audio.name);
75 75
76 76
77 Example: Switching to the first audio input 77 Example: Switching to the first audio input
78 =========================================== 78 ===========================================
79 79
80 .. code-block:: c 80 .. code-block:: c
81 81
82 struct v4l2_audio audio; 82 struct v4l2_audio audio;
83 83
84 memset(&audio, 0, sizeof(audio)); /* clear 84 memset(&audio, 0, sizeof(audio)); /* clear audio.mode, audio.reserved */
85 85
86 audio.index = 0; 86 audio.index = 0;
87 87
88 if (-1 == ioctl(fd, VIDIOC_S_AUDIO, &audio 88 if (-1 == ioctl(fd, VIDIOC_S_AUDIO, &audio)) {
89 perror("VIDIOC_S_AUDIO"); 89 perror("VIDIOC_S_AUDIO");
90 exit(EXIT_FAILURE); 90 exit(EXIT_FAILURE);
91 } 91 }
92 92
93 .. [#f1] 93 .. [#f1]
94 Actually struct :c:type:`v4l2_audio` ought 94 Actually struct :c:type:`v4l2_audio` ought to have a
95 ``tuner`` field like struct :c:type:`v4l2_i 95 ``tuner`` field like struct :c:type:`v4l2_input`, not
96 only making the API more consistent but als 96 only making the API more consistent but also permitting radio devices
97 with multiple tuners. 97 with multiple tuners.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.