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