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