98 lines · plain
1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later2 3.. _audio:4 5************************6Audio Inputs and Outputs7************************8 9Audio inputs and outputs are physical connectors of a device. Video10capture devices have inputs, output devices have outputs, zero or more11each. Radio devices have no audio inputs or outputs. They have exactly12one tuner which in fact *is* an audio source, but this API associates13tuners with video inputs or outputs only, and radio devices have none of14these. [#f1]_ A connector on a TV card to loop back the received audio15signal to a sound card is not considered an audio output.16 17Audio and video inputs and outputs are associated. Selecting a video18source also selects an audio source. This is most evident when the video19and audio source is a tuner. Further audio connectors can combine with20more than one video input or output. Assumed two composite video inputs21and two audio inputs exist, there may be up to four valid combinations.22The relation of video and audio connectors is defined in the23``audioset`` field of the respective struct24:c:type:`v4l2_input` or struct25:c:type:`v4l2_output`, where each bit represents the index26number, starting at zero, of one audio input or output.27 28To learn about the number and attributes of the available inputs and29outputs applications can enumerate them with the30:ref:`VIDIOC_ENUMAUDIO` and31:ref:`VIDIOC_ENUMAUDOUT <VIDIOC_ENUMAUDOUT>` ioctl, respectively.32The struct :c:type:`v4l2_audio` returned by the33:ref:`VIDIOC_ENUMAUDIO` ioctl also contains signal34status information applicable when the current audio input is queried.35 36The :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` and37:ref:`VIDIOC_G_AUDOUT <VIDIOC_G_AUDOUT>` ioctls report the current38audio input and output, respectively.39 40.. note::41 42 Note that, unlike :ref:`VIDIOC_G_INPUT <VIDIOC_G_INPUT>` and43 :ref:`VIDIOC_G_OUTPUT <VIDIOC_G_OUTPUT>` these ioctls return a44 structure as :ref:`VIDIOC_ENUMAUDIO` and45 :ref:`VIDIOC_ENUMAUDOUT <VIDIOC_ENUMAUDOUT>` do, not just an index.46 47To select an audio input and change its properties applications call the48:ref:`VIDIOC_S_AUDIO <VIDIOC_G_AUDIO>` ioctl. To select an audio49output (which presently has no changeable properties) applications call50the :ref:`VIDIOC_S_AUDOUT <VIDIOC_G_AUDOUT>` ioctl.51 52Drivers must implement all audio input ioctls when the device has53multiple selectable audio inputs, all audio output ioctls when the54device has multiple selectable audio outputs. When the device has any55audio inputs or outputs the driver must set the ``V4L2_CAP_AUDIO`` flag56in the struct :c:type:`v4l2_capability` returned by57the :ref:`VIDIOC_QUERYCAP` ioctl.58 59 60Example: Information about the current audio input61==================================================62 63.. code-block:: c64 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 input78===========================================79 80.. code-block:: c81 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 a95 ``tuner`` field like struct :c:type:`v4l2_input`, not96 only making the API more consistent but also permitting radio devices97 with multiple tuners.98