5 This file is part of PulseAudio.
7 Copyright 2004-2006 Lennart Poettering
8 Copyright 2006 Pierre Ossman <ossman@cendio.se> for Cendio AB
10 PulseAudio is free software; you can redistribute it and/or modify
11 it under the terms of the GNU Lesser General Public License as published
12 by the Free Software Foundation; either version 2.1 of the License,
13 or (at your option) any later version.
15 PulseAudio is distributed in the hope that it will be useful, but
16 WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 General Public License for more details.
20 You should have received a copy of the GNU Lesser General Public License
21 along with PulseAudio; if not, write to the Free Software
22 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
29 #include <pulse/cdecl.h>
30 #include <pulse/gccmacro.h>
31 #include <pulse/sample.h>
32 #include <pulse/channelmap.h>
33 #include <pulse/version.h>
35 /** \page volume Volume Control
37 * \section overv_sec Overview
39 * Sinks, sources, sink inputs and samples can all have their own volumes.
40 * To deal with these, The PulseAudio libray contains a number of functions
43 * The basic volume type in PulseAudio is the \ref pa_volume_t type. Most of
44 * the time, applications will use the aggregated pa_cvolume structure that
45 * can store the volume of all channels at once.
47 * Volumes commonly span between muted (0%), and normal (100%). It is possible
48 * to set volumes to higher than 100%, but clipping might occur.
50 * \section calc_sec Calculations
52 * The volumes in PulseAudio are logarithmic in nature and applications
53 * shouldn't perform calculations with them directly. Instead, they should
54 * be converted to and from either dB or a linear scale:
56 * \li dB - pa_sw_volume_from_dB() / pa_sw_volume_to_dB()
57 * \li Linear - pa_sw_volume_from_linear() / pa_sw_volume_to_linear()
59 * For simple multiplication, pa_sw_volume_multiply() and
60 * pa_sw_cvolume_multiply() can be used.
62 * Calculations can only be reliably performed on software volumes
63 * as it is commonly unknown what scale hardware volumes relate to.
65 * The functions described above are only valid when used with
66 * software volumes. Hence it is usually a better idea to treat all
67 * volume values as opaque with a range from PA_VOLUME_MUTED (0%) to
68 * PA_VOLUME_NORM (100%) and to refrain from any calculations with
71 * \section conv_sec Convenience Functions
73 * To handle the pa_cvolume structure, the PulseAudio library provides a
74 * number of convenienc functions:
76 * \li pa_cvolume_valid() - Tests if a pa_cvolume structure is valid.
77 * \li pa_cvolume_equal() - Tests if two pa_cvolume structures are identical.
78 * \li pa_cvolume_channels_equal_to() - Tests if all channels of a pa_cvolume
79 * structure have a given volume.
80 * \li pa_cvolume_is_muted() - Tests if all channels of a pa_cvolume
81 * structure are muted.
82 * \li pa_cvolume_is_norm() - Tests if all channels of a pa_cvolume structure
83 * are at a normal volume.
84 * \li pa_cvolume_set() - Set all channels of a pa_cvolume structure to a
86 * \li pa_cvolume_reset() - Set all channels of a pa_cvolume structure to a
88 * \li pa_cvolume_mute() - Set all channels of a pa_cvolume structure to a
90 * \li pa_cvolume_avg() - Return the average volume of all channels.
91 * \li pa_cvolume_snprint() - Pretty print a pa_cvolume structure.
95 * Constants and routines for volume handling */
99 /** Volume specification:
100 * PA_VOLUME_MUTED: silence;
101 * < PA_VOLUME_NORM: decreased volume;
102 * PA_VOLUME_NORM: normal volume;
103 * > PA_VOLUME_NORM: increased volume */
104 typedef uint32_t pa_volume_t;
106 /** Normal volume (100%, 0 dB) */
107 #define PA_VOLUME_NORM ((pa_volume_t) 0x10000U)
109 /** Muted volume (0%, -inf dB) */
110 #define PA_VOLUME_MUTED ((pa_volume_t) 0U)
112 /** Maximum volume we can store. \since 0.9.15 */
113 #define PA_VOLUME_MAX ((pa_volume_t) UINT32_MAX)
115 /** A structure encapsulating a per-channel volume */
116 typedef struct pa_cvolume {
117 uint8_t channels; /**< Number of channels */
118 pa_volume_t values[PA_CHANNELS_MAX]; /**< Per-channel volume */
121 /** Return non-zero when *a == *b */
122 int pa_cvolume_equal(const pa_cvolume *a, const pa_cvolume *b) PA_GCC_PURE;
124 /** Initialize the specified volume and return a pointer to
125 * it. The sample spec will have a defined state but
126 * pa_cvolume_valid() will fail for it. \since 0.9.13 */
127 pa_cvolume* pa_cvolume_init(pa_cvolume *a);
129 /** Set the volume of all channels to PA_VOLUME_NORM */
130 #define pa_cvolume_reset(a, n) pa_cvolume_set((a), (n), PA_VOLUME_NORM)
132 /** Set the volume of all channels to PA_VOLUME_MUTED */
133 #define pa_cvolume_mute(a, n) pa_cvolume_set((a), (n), PA_VOLUME_MUTED)
135 /** Set the volume of all channels to the specified parameter */
136 pa_cvolume* pa_cvolume_set(pa_cvolume *a, unsigned channels, pa_volume_t v);
138 /** Maximum length of the strings returned by
139 * pa_cvolume_snprint(). Please note that this value can change with
140 * any release without warning and without being considered API or ABI
141 * breakage. You should not use this definition anywhere where it
142 * might become part of an ABI.*/
143 #define PA_CVOLUME_SNPRINT_MAX 320
145 /** Pretty print a volume structure */
146 char *pa_cvolume_snprint(char *s, size_t l, const pa_cvolume *c);
148 /** Maximum length of the strings returned by
149 * pa_cvolume_snprint_dB(). Please note that this value can change with
150 * any release without warning and without being considered API or ABI
151 * breakage. You should not use this definition anywhere where it
152 * might become part of an ABI. \since 0.9.13 */
153 #define PA_SW_CVOLUME_SNPRINT_DB_MAX 448
155 /** Pretty print a volume structure but show dB values. \since 0.9.13 */
156 char *pa_sw_cvolume_snprint_dB(char *s, size_t l, const pa_cvolume *c);
158 /** Maximum length of the strings returned by
159 * pa_volume_snprint(). Please note that this value can change with
160 * any release without warning and without being considered API or ABI
161 * breakage. You should not use this definition anywhere where it
162 * might become part of an ABI. \since 0.9.15 */
163 #define PA_VOLUME_SNPRINT_MAX 10
165 /** Pretty print a volume \since 0.9.15 */
166 char *pa_volume_snprint(char *s, size_t l, pa_volume_t v);
168 /** Maximum length of the strings returned by
169 * pa_volume_snprint_dB(). Please note that this value can change with
170 * any release without warning and without being considered API or ABI
171 * breakage. You should not use this definition anywhere where it
172 * might become part of an ABI. \since 0.9.15 */
173 #define PA_SW_VOLUME_SNPRINT_DB_MAX 10
175 /** Pretty print a volume but show dB values. \since 0.9.15 */
176 char *pa_sw_volume_snprint_dB(char *s, size_t l, pa_volume_t v);
178 /** Return the average volume of all channels */
179 pa_volume_t pa_cvolume_avg(const pa_cvolume *a) PA_GCC_PURE;
181 /** Return the average volume of all channels that are included in the
182 * specified channel map with the specified channel position mask. If
183 * cm is NULL this call is identical to pa_cvolume_avg(). If no
184 * channel is selected the returned value will be
185 * PA_VOLUME_MUTED. \since 0.9.16 */
186 pa_volume_t pa_cvolume_avg_mask(const pa_cvolume *a, const pa_channel_map *cm, pa_channel_position_mask_t mask) PA_GCC_PURE;
188 /** Return the maximum volume of all channels. \since 0.9.12 */
189 pa_volume_t pa_cvolume_max(const pa_cvolume *a) PA_GCC_PURE;
191 /** Return the maximum volume of all channels that are included in the
192 * specified channel map with the specified channel position mask. If
193 * cm is NULL this call is identical to pa_cvolume_max(). If no
194 * channel is selected the returned value will be PA_VOLUME_MUTED.
196 pa_volume_t pa_cvolume_max_mask(const pa_cvolume *a, const pa_channel_map *cm, pa_channel_position_mask_t mask) PA_GCC_PURE;
198 /** Return TRUE when the passed cvolume structure is valid, FALSE otherwise */
199 int pa_cvolume_valid(const pa_cvolume *v) PA_GCC_PURE;
201 /** Return non-zero if the volume of all channels is equal to the specified value */
202 int pa_cvolume_channels_equal_to(const pa_cvolume *a, pa_volume_t v) PA_GCC_PURE;
204 /** Return 1 if the specified volume has all channels muted */
205 #define pa_cvolume_is_muted(a) pa_cvolume_channels_equal_to((a), PA_VOLUME_MUTED)
207 /** Return 1 if the specified volume has all channels on normal level */
208 #define pa_cvolume_is_norm(a) pa_cvolume_channels_equal_to((a), PA_VOLUME_NORM)
210 /** Multiply two volume specifications, return the result. This uses
211 * PA_VOLUME_NORM as neutral element of multiplication. This is only
212 * valid for software volumes! */
213 pa_volume_t pa_sw_volume_multiply(pa_volume_t a, pa_volume_t b) PA_GCC_CONST;
215 /** Multiply two per-channel volumes and return the result in
216 * *dest. This is only valid for software volumes! a, b and dest may
217 * point to the same structure. */
218 pa_cvolume *pa_sw_cvolume_multiply(pa_cvolume *dest, const pa_cvolume *a, const pa_cvolume *b);
220 /** Multiply a per-channel volume with a scalar volume and return the
221 * result in *dest. This is only valid for software volumes! a
222 * and dest may point to the same structure. \since
224 pa_cvolume *pa_sw_cvolume_multiply_scalar(pa_cvolume *dest, const pa_cvolume *a, pa_volume_t b);
226 /** Divide two volume specifications, return the result. This uses
227 * PA_VOLUME_NORM as neutral element of division. This is only valid
228 * for software volumes! If a division by zero is tried the result
229 * will be 0. \since 0.9.13 */
230 pa_volume_t pa_sw_volume_divide(pa_volume_t a, pa_volume_t b) PA_GCC_CONST;
232 /** Divide two per-channel volumes and return the result in
233 * *dest. This is only valid for software volumes! a, b
234 * and dest may point to the same structure. \since 0.9.13 */
235 pa_cvolume *pa_sw_cvolume_divide(pa_cvolume *dest, const pa_cvolume *a, const pa_cvolume *b);
237 /** Divide a per-channel volume by a scalar volume and return the
238 * result in *dest. This is only valid for software volumes! a
239 * and dest may point to the same structure. \since
241 pa_cvolume *pa_sw_cvolume_divide_scalar(pa_cvolume *dest, const pa_cvolume *a, pa_volume_t b);
243 /** Convert a decibel value to a volume (amplitude, not power). This is only valid for software volumes! */
244 pa_volume_t pa_sw_volume_from_dB(double f) PA_GCC_CONST;
246 /** Convert a volume to a decibel value (amplitude, not power). This is only valid for software volumes! */
247 double pa_sw_volume_to_dB(pa_volume_t v) PA_GCC_CONST;
249 /** Convert a linear factor to a volume. This is only valid for software volumes! */
250 pa_volume_t pa_sw_volume_from_linear(double v) PA_GCC_CONST;
252 /** Convert a volume to a linear factor. This is only valid for software volumes! */
253 double pa_sw_volume_to_linear(pa_volume_t v) PA_GCC_CONST;
256 #define PA_DECIBEL_MININFTY ((double) -INFINITY)
258 /** This floor value is used as minus infinity when using pa_volume_{to,from}_dB(). */
259 #define PA_DECIBEL_MININFTY ((double) -200.0)
262 /** Remap a volume from one channel mapping to a different channel mapping. \since 0.9.12 */
263 pa_cvolume *pa_cvolume_remap(pa_cvolume *v, const pa_channel_map *from, const pa_channel_map *to);
265 /** Return non-zero if the specified volume is compatible with the
266 * specified sample spec. \since 0.9.13 */
267 int pa_cvolume_compatible(const pa_cvolume *v, const pa_sample_spec *ss) PA_GCC_PURE;
269 /** Return non-zero if the specified volume is compatible with the
270 * specified sample spec. \since 0.9.15 */
271 int pa_cvolume_compatible_with_channel_map(const pa_cvolume *v, const pa_channel_map *cm) PA_GCC_PURE;
273 /** Calculate a 'balance' value for the specified volume with the
274 * specified channel map. The return value will range from -1.0f
275 * (left) to +1.0f (right). If no balance value is applicable to this
276 * channel map the return value will always be 0.0f. See
277 * pa_channel_map_can_balance(). \since 0.9.15 */
278 float pa_cvolume_get_balance(const pa_cvolume *v, const pa_channel_map *map) PA_GCC_PURE;
280 /** Adjust the 'balance' value for the specified volume with the
281 * specified channel map. v will be modified in place and
282 * returned. The balance is a value between -1.0f and +1.0f. This
283 * operation might not be reversible! Also, after this call
284 * pa_cvolume_get_balance() is not guaranteed to actually return the
285 * requested balance value (e.g. when the input volume was zero anyway for
286 * all channels). If no balance value is applicable to
287 * this channel map the volume will not be modified. See
288 * pa_channel_map_can_balance(). \since 0.9.15 */
289 pa_cvolume* pa_cvolume_set_balance(pa_cvolume *v, const pa_channel_map *map, float new_balance);
291 /** Calculate a 'fade' value (i.e. 'balance' between front and rear)
292 * for the specified volume with the specified channel map. The return
293 * value will range from -1.0f (rear) to +1.0f (left). If no fade
294 * value is applicable to this channel map the return value will
295 * always be 0.0f. See pa_channel_map_can_fade(). \since 0.9.15 */
296 float pa_cvolume_get_fade(const pa_cvolume *v, const pa_channel_map *map) PA_GCC_PURE;
298 /** Adjust the 'fade' value (i.e. 'balance' between front and rear)
299 * for the specified volume with the specified channel map. v will be
300 * modified in place and returned. The balance is a value between
301 * -1.0f and +1.0f. This operation might not be reversible! Also,
302 * after this call pa_cvolume_get_fade() is not guaranteed to actually
303 * return the requested fade value (e.g. when the input volume was
304 * zero anyway for all channels). If no fade value is applicable to
305 * this channel map the volume will not be modified. See
306 * pa_channel_map_can_fade(). \since 0.9.15 */
307 pa_cvolume* pa_cvolume_set_fade(pa_cvolume *v, const pa_channel_map *map, float new_fade);
309 /** Scale the passed pa_cvolume structure so that the maximum volume
310 * of all channels equals max. The proportions between the channel
311 * volumes are kept. \since 0.9.15 */
312 pa_cvolume* pa_cvolume_scale(pa_cvolume *v, pa_volume_t max);
314 /** Scale the passed pa_cvolume structure so that the maximum volume
315 * of all channels selected via cm/mask equals max. This also modifies
316 * the volume of those channels that are unmasked. The proportions
317 * between the channel volumes are kept. \since 0.9.16 */
318 pa_cvolume* pa_cvolume_scale_mask(pa_cvolume *v, pa_volume_t max, pa_channel_map *cm, pa_channel_position_mask_t mask);
320 /** Set the passed volume to all channels at the specified channel
321 * position. Will return the updated volume struct, or NULL if there
322 * is no channel at the position specified. You can check if a channel
323 * map includes a specific position by calling
324 * pa_channel_map_has_position(). \since 0.9.16 */
325 pa_cvolume* pa_cvolume_set_position(pa_cvolume *cv, const pa_channel_map *map, pa_channel_position_t t, pa_volume_t v);
327 /** Get the maximum volume of all channels at the specified channel
328 * position. Will return 0 if there is no channel at the position
329 * specified. You can check if a channel map includes a specific
330 * position by calling pa_channel_map_has_position(). \since 0.9.16 */
331 pa_volume_t pa_cvolume_get_position(pa_cvolume *cv, const pa_channel_map *map, pa_channel_position_t t) PA_GCC_PURE;
333 /** This goes through all channels in a and b and sets the
334 * corresponding channel in dest to the greater volume of both. a, b
335 * and dest may point to the same structure. \since 0.9.16 */
336 pa_cvolume* pa_cvolume_merge(pa_cvolume *dest, const pa_cvolume *a, const pa_cvolume *b);