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