Documentation/media/uapi/v4l/audio.rst

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