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