Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 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 |
Mauro Carvalho Chehab | 7347081 | 2016-07-01 13:58:44 -0300 | [diff] [blame] | 30 | :ref:`VIDIOC_ENUMAUDIO` and |
Mauro Carvalho Chehab | af4a4d0 | 2016-07-01 13:42:29 -0300 | [diff] [blame] | 31 | :ref:`VIDIOC_ENUMAUDOUT <VIDIOC_ENUMAUDIOout>` ioctl, respectively. |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 32 | The struct :ref:`v4l2_audio <v4l2-audio>` returned by the |
Mauro Carvalho Chehab | 7347081 | 2016-07-01 13:58:44 -0300 | [diff] [blame] | 33 | :ref:`VIDIOC_ENUMAUDIO` ioctl also contains signal |
Mauro Carvalho Chehab | 7898188 | 2016-06-30 22:52:34 -0300 | [diff] [blame] | 34 | :status information applicable when the current audio input is queried. |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 35 | |
Mauro Carvalho Chehab | 4e03cb7 | 2016-07-03 10:02:29 -0300 | [diff] [blame] | 36 | The :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` and |
Mauro Carvalho Chehab | af4a4d0 | 2016-07-01 13:42:29 -0300 | [diff] [blame] | 37 | :ref:`VIDIOC_G_AUDOUT <VIDIOC_G_AUDIOout>` ioctls report the current |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 38 | audio input and output, respectively. Note that, unlike |
Mauro Carvalho Chehab | 4e03cb7 | 2016-07-03 10:02:29 -0300 | [diff] [blame] | 39 | :ref:`VIDIOC_G_INPUT <VIDIOC_G_INPUT>` and |
| 40 | :ref:`VIDIOC_G_OUTPUT <VIDIOC_G_OUTPUT>` these ioctls return a |
Mauro Carvalho Chehab | 7347081 | 2016-07-01 13:58:44 -0300 | [diff] [blame] | 41 | structure as :ref:`VIDIOC_ENUMAUDIO` and |
Mauro Carvalho Chehab | af4a4d0 | 2016-07-01 13:42:29 -0300 | [diff] [blame] | 42 | :ref:`VIDIOC_ENUMAUDOUT <VIDIOC_ENUMAUDIOout>` do, not just an index. |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 43 | |
| 44 | To select an audio input and change its properties applications call the |
Mauro Carvalho Chehab | af4a4d0 | 2016-07-01 13:42:29 -0300 | [diff] [blame] | 45 | :ref:`VIDIOC_S_AUDIO <VIDIOC_G_AUDIO>` ioctl. To select an audio |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 46 | output (which presently has no changeable properties) applications call |
Mauro Carvalho Chehab | af4a4d0 | 2016-07-01 13:42:29 -0300 | [diff] [blame] | 47 | the :ref:`VIDIOC_S_AUDOUT <VIDIOC_G_AUDIOout>` ioctl. |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 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 |
Mauro Carvalho Chehab | 7347081 | 2016-07-01 13:58:44 -0300 | [diff] [blame] | 54 | the :ref:`VIDIOC_QUERYCAP` ioctl. |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 55 | |
| 56 | |
| 57 | .. code-block:: c |
Mauro Carvalho Chehab | da1621c | 2016-07-03 11:24:58 -0300 | [diff] [blame] | 58 | :caption: Example 1.3. Information about the current audio input |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 59 | |
| 60 | struct v4l2_audio audio; |
| 61 | |
| 62 | memset(&audio, 0, sizeof(audio)); |
| 63 | |
| 64 | if (-1 == ioctl(fd, VIDIOC_G_AUDIO, &audio)) { |
| 65 | perror("VIDIOC_G_AUDIO"); |
| 66 | exit(EXIT_FAILURE); |
| 67 | } |
| 68 | |
| 69 | printf("Current input: %s\\n", audio.name); |
| 70 | |
| 71 | |
| 72 | .. code-block:: c |
Mauro Carvalho Chehab | da1621c | 2016-07-03 11:24:58 -0300 | [diff] [blame] | 73 | :caption: Example 1.4. Switching to the first audio input |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 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)) { |
| 82 | perror("VIDIOC_S_AUDIO"); |
| 83 | exit(EXIT_FAILURE); |
| 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. |
| 91 | |
| 92 | |
| 93 | .. ------------------------------------------------------------------------------ |
| 94 | .. This file was automatically converted from DocBook-XML with the dbxml |
| 95 | .. library (https://github.com/return42/sphkerneldoc). The origin XML comes |
| 96 | .. from the linux kernel, refer to: |
| 97 | .. |
| 98 | .. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook |
| 99 | .. ------------------------------------------------------------------------------ |