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