Documentation/media/uapi/v4l/vidioc-g-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 .. _VIDIOC_G_AUDIO:
  11
  12 ************************************
  13 ioctl VIDIOC_G_AUDIO, VIDIOC_S_AUDIO
  14 ************************************
  15
  16 Name
  17 ====
  18
  19 VIDIOC_G_AUDIO - VIDIOC_S_AUDIO - Query or select the current audio input and its attributes
  20
  21
  22 Synopsis
  23 ========
  24
  25 .. c:function:: int ioctl( int fd, VIDIOC_G_AUDIO, struct v4l2_audio *argp )
  26     :name: VIDIOC_G_AUDIO
  27
  28 .. c:function:: int ioctl( int fd, VIDIOC_S_AUDIO, const struct v4l2_audio *argp )
  29     :name: VIDIOC_S_AUDIO
  30
  31
  32 Arguments
  33 =========
  34
  35 ``fd``
  36     File descriptor returned by :ref:`open() <func-open>`.
  37
  38 ``argp``
  39     Pointer to struct :c:type:`v4l2_audio`.
  40
  41
  42 Description
  43 ===========
  44
  45 To query the current audio input applications zero out the ``reserved``
  46 array of a struct :c:type:`v4l2_audio` and call the
  47 :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` ioctl with a pointer to this structure. Drivers fill
  48 the rest of the structure or return an ``EINVAL`` error code when the device
  49 has no audio inputs, or none which combine with the current video input.
  50
  51 Audio inputs have one writable property, the audio mode. To select the
  52 current audio input *and* change the audio mode, applications initialize
  53 the ``index`` and ``mode`` fields, and the ``reserved`` array of a
  54 struct :c:type:`v4l2_audio` structure and call the :ref:`VIDIOC_S_AUDIO <VIDIOC_G_AUDIO>`
  55 ioctl. Drivers may switch to a different audio mode if the request
  56 cannot be satisfied. However, this is a write-only ioctl, it does not
  57 return the actual new audio mode.
  58
  59
  60 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
  61
  62 .. c:type:: v4l2_audio
  63
  64 .. flat-table:: struct v4l2_audio
  65     :header-rows:  0
  66     :stub-columns: 0
  67     :widths:       1 1 2
  68
  69     * - __u32
  70       - ``index``
  71       - Identifies the audio input, set by the driver or application.
  72     * - __u8
  73       - ``name``\ [32]
  74       - Name of the audio input, a NUL-terminated ASCII string, for
  75         example: "Line In". This information is intended for the user,
  76         preferably the connector label on the device itself.
  77     * - __u32
  78       - ``capability``
  79       - Audio capability flags, see :ref:`audio-capability`.
  80     * - __u32
  81       - ``mode``
  82       - Audio mode flags set by drivers and applications (on
  83         :ref:`VIDIOC_S_AUDIO <VIDIOC_G_AUDIO>` ioctl), see :ref:`audio-mode`.
  84     * - __u32
  85       - ``reserved``\ [2]
  86       - Reserved for future extensions. Drivers and applications must set
  87         the array to zero.
  88
  89
  90
  91 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
  92
  93 .. _audio-capability:
  94
  95 .. flat-table:: Audio Capability Flags
  96     :header-rows:  0
  97     :stub-columns: 0
  98     :widths:       3 1 4
  99
 100     * - ``V4L2_AUDCAP_STEREO``
 101       - 0x00001
 102       - This is a stereo input. The flag is intended to automatically
 103         disable stereo recording etc. when the signal is always monaural.
 104         The API provides no means to detect if stereo is *received*,
 105         unless the audio input belongs to a tuner.
 106     * - ``V4L2_AUDCAP_AVL``
 107       - 0x00002
 108       - Automatic Volume Level mode is supported.
 109
 110
 111
 112 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 113
 114 .. _audio-mode:
 115
 116 .. flat-table:: Audio Mode Flags
 117     :header-rows:  0
 118     :stub-columns: 0
 119     :widths:       3 1 4
 120
 121     * - ``V4L2_AUDMODE_AVL``
 122       - 0x00001
 123       - AVL mode is on.
 124
 125
 126 Return Value
 127 ============
 128
 129 On success 0 is returned, on error -1 and the ``errno`` variable is set
 130 appropriately. The generic error codes are described at the
 131 :ref:`Generic Error Codes <gen-errors>` chapter.
 132
 133 EINVAL
 134     No audio inputs combine with the current video input, or the number
 135     of the selected audio input is out of bounds or it does not combine.