| 1 |
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later |
| 2 |
.. c:namespace:: V4L |
| 3 |
|
| 4 |
.. _audio: |
| 5 |
|
| 6 |
************************ |
| 7 |
Audio Inputs and Outputs |
| 8 |
************************ |
| 9 |
|
| 10 |
Audio inputs and outputs are physical connectors of a device. Video |
| 11 |
capture devices have inputs, output devices have outputs, zero or more |
| 12 |
each. Radio devices have no audio inputs or outputs. They have exactly |
| 13 |
one tuner which in fact *is* an audio source, but this API associates |
| 14 |
tuners with video inputs or outputs only, and radio devices have none of |
| 15 |
these. [#f1]_ A connector on a TV card to loop back the received audio |
| 16 |
signal to a sound card is not considered an audio output. |
| 17 |
|
| 18 |
Audio and video inputs and outputs are associated. Selecting a video |
| 19 |
source also selects an audio source. This is most evident when the video |
| 20 |
and audio source is a tuner. Further audio connectors can combine with |
| 21 |
more than one video input or output. Assumed two composite video inputs |
| 22 |
and two audio inputs exist, there may be up to four valid combinations. |
| 23 |
The 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 |
| 27 |
number, starting at zero, of one audio input or output. |
| 28 |
|
| 29 |
To learn about the number and attributes of the available inputs and |
| 30 |
outputs applications can enumerate them with the |
| 31 |
:ref:`VIDIOC_ENUMAUDIO` and |
| 32 |
:ref:`VIDIOC_ENUMAUDOUT <VIDIOC_ENUMAUDOUT>` ioctl, respectively. |
| 33 |
The struct :c:type:`v4l2_audio` returned by the |
| 34 |
:ref:`VIDIOC_ENUMAUDIO` ioctl also contains signal |
| 35 |
status information applicable when the current audio input is queried. |
| 36 |
|
| 37 |
The :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` and |
| 38 |
:ref:`VIDIOC_G_AUDOUT <VIDIOC_G_AUDOUT>` ioctls report the current |
| 39 |
audio 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 |
|
| 48 |
To select an audio input and change its properties applications call the |
| 49 |
:ref:`VIDIOC_S_AUDIO <VIDIOC_G_AUDIO>` ioctl. To select an audio |
| 50 |
output (which presently has no changeable properties) applications call |
| 51 |
the :ref:`VIDIOC_S_AUDOUT <VIDIOC_G_AUDOUT>` ioctl. |
| 52 |
|
| 53 |
Drivers must implement all audio input ioctls when the device has |
| 54 |
multiple selectable audio inputs, all audio output ioctls when the |
| 55 |
device has multiple selectable audio outputs. When the device has any |
| 56 |
audio inputs or outputs the driver must set the ``V4L2_CAP_AUDIO`` flag |
| 57 |
in the struct :c:type:`v4l2_capability` returned by |
| 58 |
the :ref:`VIDIOC_QUERYCAP` ioctl. |
| 59 |
|
| 60 |
|
| 61 |
Example: 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 |
|
| 78 |
Example: 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. |