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