0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002
0003 .. _audio:
0004
0005 ************************
0006 Audio Inputs and Outputs
0007 ************************
0008
0009 Audio inputs and outputs are physical connectors of a device. Video
0010 capture devices have inputs, output devices have outputs, zero or more
0011 each. Radio devices have no audio inputs or outputs. They have exactly
0012 one tuner which in fact *is* an audio source, but this API associates
0013 tuners with video inputs or outputs only, and radio devices have none of
0014 these. [#f1]_ A connector on a TV card to loop back the received audio
0015 signal to a sound card is not considered an audio output.
0016
0017 Audio and video inputs and outputs are associated. Selecting a video
0018 source also selects an audio source. This is most evident when the video
0019 and audio source is a tuner. Further audio connectors can combine with
0020 more than one video input or output. Assumed two composite video inputs
0021 and two audio inputs exist, there may be up to four valid combinations.
0022 The relation of video and audio connectors is defined in the
0023 ``audioset`` field of the respective struct
0024 :c:type:`v4l2_input` or struct
0025 :c:type:`v4l2_output`, where each bit represents the index
0026 number, starting at zero, of one audio input or output.
0027
0028 To learn about the number and attributes of the available inputs and
0029 outputs applications can enumerate them with the
0030 :ref:`VIDIOC_ENUMAUDIO` and
0031 :ref:`VIDIOC_ENUMAUDOUT <VIDIOC_ENUMAUDOUT>` ioctl, respectively.
0032 The struct :c:type:`v4l2_audio` returned by the
0033 :ref:`VIDIOC_ENUMAUDIO` ioctl also contains signal
0034 status information applicable when the current audio input is queried.
0035
0036 The :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` and
0037 :ref:`VIDIOC_G_AUDOUT <VIDIOC_G_AUDOUT>` ioctls report the current
0038 audio input and output, respectively.
0039
0040 .. note::
0041
0042 Note that, unlike :ref:`VIDIOC_G_INPUT <VIDIOC_G_INPUT>` and
0043 :ref:`VIDIOC_G_OUTPUT <VIDIOC_G_OUTPUT>` these ioctls return a
0044 structure as :ref:`VIDIOC_ENUMAUDIO` and
0045 :ref:`VIDIOC_ENUMAUDOUT <VIDIOC_ENUMAUDOUT>` do, not just an index.
0046
0047 To select an audio input and change its properties applications call the
0048 :ref:`VIDIOC_S_AUDIO <VIDIOC_G_AUDIO>` ioctl. To select an audio
0049 output (which presently has no changeable properties) applications call
0050 the :ref:`VIDIOC_S_AUDOUT <VIDIOC_G_AUDOUT>` ioctl.
0051
0052 Drivers must implement all audio input ioctls when the device has
0053 multiple selectable audio inputs, all audio output ioctls when the
0054 device has multiple selectable audio outputs. When the device has any
0055 audio inputs or outputs the driver must set the ``V4L2_CAP_AUDIO`` flag
0056 in the struct :c:type:`v4l2_capability` returned by
0057 the :ref:`VIDIOC_QUERYCAP` ioctl.
0058
0059
0060 Example: Information about the current audio input
0061 ==================================================
0062
0063 .. code-block:: c
0064
0065 struct v4l2_audio audio;
0066
0067 memset(&audio, 0, sizeof(audio));
0068
0069 if (-1 == ioctl(fd, VIDIOC_G_AUDIO, &audio)) {
0070 perror("VIDIOC_G_AUDIO");
0071 exit(EXIT_FAILURE);
0072 }
0073
0074 printf("Current input: %s\\n", audio.name);
0075
0076
0077 Example: Switching to the first audio input
0078 ===========================================
0079
0080 .. code-block:: c
0081
0082 struct v4l2_audio audio;
0083
0084 memset(&audio, 0, sizeof(audio)); /* clear audio.mode, audio.reserved */
0085
0086 audio.index = 0;
0087
0088 if (-1 == ioctl(fd, VIDIOC_S_AUDIO, &audio)) {
0089 perror("VIDIOC_S_AUDIO");
0090 exit(EXIT_FAILURE);
0091 }
0092
0093 .. [#f1]
0094 Actually struct :c:type:`v4l2_audio` ought to have a
0095 ``tuner`` field like struct :c:type:`v4l2_input`, not
0096 only making the API more consistent but also permitting radio devices
0097 with multiple tuners.
