]>
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 | |
24 | :ref:`v4l2_input <v4l2-input>` or struct | |
25 | :ref:`v4l2_output <v4l2-output>`, where each bit represents the index | |
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. |
5377d91f | 32 | The struct :ref:`v4l2_audio <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 | ||
40 | .. note:: Note that, unlike :ref:`VIDIOC_G_INPUT <VIDIOC_G_INPUT>` and | |
41 | :ref:`VIDIOC_G_OUTPUT <VIDIOC_G_OUTPUT>` these ioctls return a | |
42 | structure as :ref:`VIDIOC_ENUMAUDIO` and | |
43 | :ref:`VIDIOC_ENUMAUDOUT <VIDIOC_ENUMAUDOUT>` do, not just an index. | |
5377d91f MH |
44 | |
45 | To select an audio input and change its properties applications call the | |
af4a4d0d | 46 | :ref:`VIDIOC_S_AUDIO <VIDIOC_G_AUDIO>` ioctl. To select an audio |
5377d91f | 47 | output (which presently has no changeable properties) applications call |
9f97b306 | 48 | the :ref:`VIDIOC_S_AUDOUT <VIDIOC_G_AUDOUT>` ioctl. |
5377d91f MH |
49 | |
50 | Drivers must implement all audio input ioctls when the device has | |
51 | multiple selectable audio inputs, all audio output ioctls when the | |
52 | device has multiple selectable audio outputs. When the device has any | |
53 | audio inputs or outputs the driver must set the ``V4L2_CAP_AUDIO`` flag | |
54 | in the struct :ref:`v4l2_capability <v4l2-capability>` returned by | |
7347081e | 55 | the :ref:`VIDIOC_QUERYCAP` ioctl. |
5377d91f MH |
56 | |
57 | ||
282f02cb MCC |
58 | Example: Information about the current audio input |
59 | ================================================== | |
60 | ||
5377d91f MH |
61 | .. code-block:: c |
62 | ||
63 | struct v4l2_audio audio; | |
64 | ||
65 | memset(&audio, 0, sizeof(audio)); | |
66 | ||
67 | if (-1 == ioctl(fd, VIDIOC_G_AUDIO, &audio)) { | |
0579e6e3 MCC |
68 | perror("VIDIOC_G_AUDIO"); |
69 | exit(EXIT_FAILURE); | |
5377d91f MH |
70 | } |
71 | ||
72 | printf("Current input: %s\\n", audio.name); | |
73 | ||
74 | ||
282f02cb MCC |
75 | Example: Switching to the first audio input |
76 | =========================================== | |
77 | ||
5377d91f MH |
78 | .. code-block:: c |
79 | ||
80 | struct v4l2_audio audio; | |
81 | ||
82 | memset(&audio, 0, sizeof(audio)); /* clear audio.mode, audio.reserved */ | |
83 | ||
84 | audio.index = 0; | |
85 | ||
86 | if (-1 == ioctl(fd, VIDIOC_S_AUDIO, &audio)) { | |
0579e6e3 MCC |
87 | perror("VIDIOC_S_AUDIO"); |
88 | exit(EXIT_FAILURE); | |
5377d91f MH |
89 | } |
90 | ||
4855307b | 91 | .. [#f1] |
5377d91f MH |
92 | Actually struct :ref:`v4l2_audio <v4l2-audio>` ought to have a |
93 | ``tuner`` field like struct :ref:`v4l2_input <v4l2-input>`, not | |
94 | only making the API more consistent but also permitting radio devices | |
95 | with multiple tuners. |