Documentation/media/uapi/v4l/vidioc-g-audio.rst

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