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/userspace-api/media/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********************************
13FM Transmitter Control Reference
14********************************
15
16The FM Transmitter (FM_TX) class includes controls for common features
17of FM transmissions capable devices. Currently this class includes
18parameters for audio compression, pilot tone generation, audio deviation
19limiter, RDS transmission and tuning power features.
20
21
22.. _fm-tx-control-id:
23
24FM_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
156enum 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
187For more details about RDS specification, refer to :ref:`iec62106`
188document, from CENELEC.
189