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