Documentation/media/uapi/v4l/ext-ctrls-fm-tx.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 .. _fm-tx-controls:
  11
  12 ********************************
  13 FM Transmitter Control Reference
  14 ********************************
  15
  16 The FM Transmitter (FM_TX) class includes controls for common features
  17 of FM transmissions capable devices. Currently this class includes
  18 parameters for audio compression, pilot tone generation, audio deviation
  19 limiter, RDS transmission and tuning power features.
  20
  21
  22 .. _fm-tx-control-id:
  23
  24 FM_TX Control IDs
  25 =================
  26
  27 ``V4L2_CID_FM_TX_CLASS (class)``
  28     The FM_TX class descriptor. Calling
  29     :ref:`VIDIOC_QUERYCTRL` for this control will
  30     return a description of this control class.
  31
  32 ``V4L2_CID_RDS_TX_DEVIATION (integer)``
  33     Configures RDS signal frequency deviation level in Hz. The range and
  34     step are driver-specific.
  35
  36 ``V4L2_CID_RDS_TX_PI (integer)``
  37     Sets the RDS Programme Identification field for transmission.
  38
  39 ``V4L2_CID_RDS_TX_PTY (integer)``
  40     Sets the RDS Programme Type field for transmission. This encodes up
  41     to 31 pre-defined programme types.
  42
  43 ``V4L2_CID_RDS_TX_PS_NAME (string)``
  44     Sets the Programme Service name (PS_NAME) for transmission. It is
  45     intended for static display on a receiver. It is the primary aid to
  46     listeners in programme service identification and selection. In
  47     Annex E of :ref:`iec62106`, the RDS specification, there is a full
  48     description of the correct character encoding for Programme Service
  49     name strings. Also from RDS specification, PS is usually a single
  50     eight character text. However, it is also possible to find receivers
  51     which can scroll strings sized as 8 x N characters. So, this control
  52     must be configured with steps of 8 characters. The result is it must
  53     always contain a string with size multiple of 8.
  54
  55 ``V4L2_CID_RDS_TX_RADIO_TEXT (string)``
  56     Sets the Radio Text info for transmission. It is a textual
  57     description of what is being broadcasted. RDS Radio Text can be
  58     applied when broadcaster wishes to transmit longer PS names,
  59     programme-related information or any other text. In these cases,
  60     RadioText should be used in addition to ``V4L2_CID_RDS_TX_PS_NAME``.
  61     The encoding for Radio Text strings is also fully described in Annex
  62     E of :ref:`iec62106`. The length of Radio Text strings depends on
  63     which RDS Block is being used to transmit it, either 32 (2A block)
  64     or 64 (2B block). However, it is also possible to find receivers
  65     which can scroll strings sized as 32 x N or 64 x N characters. So,
  66     this control must be configured with steps of 32 or 64 characters.
  67     The result is it must always contain a string with size multiple of
  68     32 or 64.
  69
  70 ``V4L2_CID_RDS_TX_MONO_STEREO (boolean)``
  71     Sets the Mono/Stereo bit of the Decoder Identification code. If set,
  72     then the audio was recorded as stereo.
  73
  74 ``V4L2_CID_RDS_TX_ARTIFICIAL_HEAD (boolean)``
  75     Sets the
  76     `Artificial Head <http://en.wikipedia.org/wiki/Artificial_head>`__
  77     bit of the Decoder Identification code. If set, then the audio was
  78     recorded using an artificial head.
  79
  80 ``V4L2_CID_RDS_TX_COMPRESSED (boolean)``
  81     Sets the Compressed bit of the Decoder Identification code. If set,
  82     then the audio is compressed.
  83
  84 ``V4L2_CID_RDS_TX_DYNAMIC_PTY (boolean)``
  85     Sets the Dynamic PTY bit of the Decoder Identification code. If set,
  86     then the PTY code is dynamically switched.
  87
  88 ``V4L2_CID_RDS_TX_TRAFFIC_ANNOUNCEMENT (boolean)``
  89     If set, then a traffic announcement is in progress.
  90
  91 ``V4L2_CID_RDS_TX_TRAFFIC_PROGRAM (boolean)``
  92     If set, then the tuned programme carries traffic announcements.
  93
  94 ``V4L2_CID_RDS_TX_MUSIC_SPEECH (boolean)``
  95     If set, then this channel broadcasts music. If cleared, then it
  96     broadcasts speech. If the transmitter doesn't make this distinction,
  97     then it should be set.
  98
  99 ``V4L2_CID_RDS_TX_ALT_FREQS_ENABLE (boolean)``
 100     If set, then transmit alternate frequencies.
 101
 102 ``V4L2_CID_RDS_TX_ALT_FREQS (__u32 array)``
 103     The alternate frequencies in kHz units. The RDS standard allows for
 104     up to 25 frequencies to be defined. Drivers may support fewer
 105     frequencies so check the array size.
 106
 107 ``V4L2_CID_AUDIO_LIMITER_ENABLED (boolean)``
 108     Enables or disables the audio deviation limiter feature. The limiter
 109     is useful when trying to maximize the audio volume, minimize
 110     receiver-generated distortion and prevent overmodulation.
 111
 112 ``V4L2_CID_AUDIO_LIMITER_RELEASE_TIME (integer)``
 113     Sets the audio deviation limiter feature release time. Unit is in
 114     useconds. Step and range are driver-specific.
 115
 116 ``V4L2_CID_AUDIO_LIMITER_DEVIATION (integer)``
 117     Configures audio frequency deviation level in Hz. The range and step
 118     are driver-specific.
 119
 120 ``V4L2_CID_AUDIO_COMPRESSION_ENABLED (boolean)``
 121     Enables or disables the audio compression feature. This feature
 122     amplifies signals below the threshold by a fixed gain and compresses
 123     audio signals above the threshold by the ratio of Threshold/(Gain +
 124     Threshold).
 125
 126 ``V4L2_CID_AUDIO_COMPRESSION_GAIN (integer)``
 127     Sets the gain for audio compression feature. It is a dB value. The
 128     range and step are driver-specific.
 129
 130 ``V4L2_CID_AUDIO_COMPRESSION_THRESHOLD (integer)``
 131     Sets the threshold level for audio compression freature. It is a dB
 132     value. The range and step are driver-specific.
 133
 134 ``V4L2_CID_AUDIO_COMPRESSION_ATTACK_TIME (integer)``
 135     Sets the attack time for audio compression feature. It is a useconds
 136     value. The range and step are driver-specific.
 137
 138 ``V4L2_CID_AUDIO_COMPRESSION_RELEASE_TIME (integer)``
 139     Sets the release time for audio compression feature. It is a
 140     useconds value. The range and step are driver-specific.
 141
 142 ``V4L2_CID_PILOT_TONE_ENABLED (boolean)``
 143     Enables or disables the pilot tone generation feature.
 144
 145 ``V4L2_CID_PILOT_TONE_DEVIATION (integer)``
 146     Configures pilot tone frequency deviation level. Unit is in Hz. The
 147     range and step are driver-specific.
 148
 149 ``V4L2_CID_PILOT_TONE_FREQUENCY (integer)``
 150     Configures pilot tone frequency value. Unit is in Hz. The range and
 151     step are driver-specific.
 152
 153 ``V4L2_CID_TUNE_PREEMPHASIS``
 154     (enum)
 155
 156 enum v4l2_preemphasis -
 157     Configures the pre-emphasis value for broadcasting. A pre-emphasis
 158     filter is applied to the broadcast to accentuate the high audio
 159     frequencies. Depending on the region, a time constant of either 50
 160     or 75 useconds is used. The enum v4l2_preemphasis defines possible
 161     values for pre-emphasis. Here they are:
 162
 163
 164
 165 .. flat-table::
 166     :header-rows:  0
 167     :stub-columns: 0
 168
 169     * - ``V4L2_PREEMPHASIS_DISABLED``
 170       - No pre-emphasis is applied.
 171     * - ``V4L2_PREEMPHASIS_50_uS``
 172       - A pre-emphasis of 50 uS is used.
 173     * - ``V4L2_PREEMPHASIS_75_uS``
 174       - A pre-emphasis of 75 uS is used.
 175
 176
 177
 178 ``V4L2_CID_TUNE_POWER_LEVEL (integer)``
 179     Sets the output power level for signal transmission. Unit is in
 180     dBuV. Range and step are driver-specific.
 181
 182 ``V4L2_CID_TUNE_ANTENNA_CAPACITOR (integer)``
 183     This selects the value of antenna tuning capacitor manually or
 184     automatically if set to zero. Unit, range and step are
 185     driver-specific.
 186
 187 For more details about RDS specification, refer to :ref:`iec62106`
 188 document, from CENELEC.