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