PulseAudio 16.1

Data Structures | Macros | Typedefs | Functions
volume.h File Reference

Constants and routines for volume handling. More...

Go to the source code of this file.

## Data Structures
struct | pa_cvolume
| A structure encapsulating a per-channel volume. More...

## Macros
#define | PA_VOLUME_NORM ((pa_volume_t) 0x10000U)
| Normal volume (100%, 0 dB) More...
#define | PA_VOLUME_MUTED ((pa_volume_t) 0U)
| Muted (minimal valid) volume (0%, -inf dB) More...
#define | PA_VOLUME_MAX ((pa_volume_t) UINT32_MAX/2)
| Maximum valid volume we can store. More...
#define | PA_VOLUME_UI_MAX (pa_sw_volume_from_dB(+11.0))
| Recommended maximum volume to show in user facing UIs. More...
#define | PA_VOLUME_INVALID ((pa_volume_t) UINT32_MAX)
| Special 'invalid' volume. More...
#define | PA_VOLUME_IS_VALID(v) ((v) <= PA_VOLUME_MAX)
| Check if volume is valid. More...
#define | PA_CLAMP_VOLUME(v) (PA_CLAMP_UNLIKELY((v), PA_VOLUME_MUTED, PA_VOLUME_MAX))
| Clamp volume to the permitted range. More...
#define | pa_cvolume_reset(a, n) pa_cvolume_set((a), (n), PA_VOLUME_NORM)
| Set the volume of the first n channels to PA_VOLUME_NORM. More...
#define | pa_cvolume_mute(a, n) pa_cvolume_set((a), (n), PA_VOLUME_MUTED)
| Set the volume of the first n channels to PA_VOLUME_MUTED. More...
#define | PA_CVOLUME_SNPRINT_MAX 320
| Maximum length of the strings returned by pa_cvolume_snprint(). More...
#define | PA_SW_CVOLUME_SNPRINT_DB_MAX 448
| Maximum length of the strings returned by pa_sw_cvolume_snprint_dB(). More...
#define | PA_CVOLUME_SNPRINT_VERBOSE_MAX 1984
| Maximum length of the strings returned by pa_cvolume_snprint_verbose(). More...
#define | PA_VOLUME_SNPRINT_MAX 10
| Maximum length of the strings returned by pa_volume_snprint(). More...
#define | PA_SW_VOLUME_SNPRINT_DB_MAX 11
| Maximum length of the strings returned by pa_sw_volume_snprint_dB(). More...
#define | PA_VOLUME_SNPRINT_VERBOSE_MAX 35
| Maximum length of the strings returned by pa_volume_snprint_verbose(). More...
#define | pa_cvolume_is_muted(a) pa_cvolume_channels_equal_to((a), PA_VOLUME_MUTED)
| Return 1 if the specified volume has all channels muted. More...
#define | pa_cvolume_is_norm(a) pa_cvolume_channels_equal_to((a), PA_VOLUME_NORM)
| Return 1 if the specified volume has all channels on normal level. More...
#define | PA_DECIBEL_MININFTY ((double) -200.0)
| This floor value is used as minus infinity when using pa_sw_volume_to_dB() / pa_sw_volume_from_dB(). More...

## Typedefs
typedef uint32_t | pa_volume_t
| Volume specification: PA_VOLUME_MUTED: silence; < PA_VOLUME_NORM: decreased volume; PA_VOLUME_NORM: normal volume; ‍PA_VOLUME_NORM: increased volume More...
typedef struct pa_cvolume | pa_cvolume
| A structure encapsulating a per-channel volume. More...

## Functions
int | pa_cvolume_equal (const pa_cvolume *a, const pa_cvolume *b) PA_GCC_PURE
| Return non-zero when *a == *b, checking that both a and b have the same number of channels and that the volumes of channels in a equal those in b. More...
pa_cvolume * | pa_cvolume_init (pa_cvolume *a)
| Initialize the specified volume and return a pointer to it. More...
pa_cvolume * | pa_cvolume_set (pa_cvolume *a, unsigned channels, pa_volume_t v)
| Set the volume of the specified number of channels to the volume v. More...
char * | pa_cvolume_snprint (char *s, size_t l, const pa_cvolume *c)
| Pretty print a volume structure. More...
char * | pa_sw_cvolume_snprint_dB (char *s, size_t l, const pa_cvolume *c)
| Pretty print a volume structure, showing dB values. More...
char * | pa_cvolume_snprint_verbose (char *s, size_t l, const pa_cvolume *c, const pa_channel_map *map, int print_dB)
| Pretty print a volume structure in a verbose way. More...
char * | pa_volume_snprint (char *s, size_t l, pa_volume_t v)
| Pretty print a volume. More...
char * | pa_sw_volume_snprint_dB (char *s, size_t l, pa_volume_t v)
| Pretty print a volume but show dB values. More...
char * | pa_volume_snprint_verbose (char *s, size_t l, pa_volume_t v, int print_dB)
| Pretty print a volume in a verbose way. More...
pa_volume_t | pa_cvolume_avg (const pa_cvolume *a) PA_GCC_PURE
| Return the average volume of all channels. More...
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
| Return the average volume of all channels that are included in the specified channel map with the specified channel position mask. More...
pa_volume_t | pa_cvolume_max (const pa_cvolume *a) PA_GCC_PURE
| Return the maximum volume of all channels. More...
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
| Return the maximum volume of all channels that are included in the specified channel map with the specified channel position mask. More...
pa_volume_t | pa_cvolume_min (const pa_cvolume *a) PA_GCC_PURE
| Return the minimum volume of all channels. More...
pa_volume_t | pa_cvolume_min_mask (const pa_cvolume *a, const pa_channel_map *cm, pa_channel_position_mask_t mask) PA_GCC_PURE
| Return the minimum volume of all channels that are included in the specified channel map with the specified channel position mask. More...
int | pa_cvolume_valid (const pa_cvolume *v) PA_GCC_PURE
| Return non-zero when the passed cvolume structure is valid. More...
int | pa_cvolume_channels_equal_to (const pa_cvolume *a, pa_volume_t v) PA_GCC_PURE
| Return non-zero if the volume of all channels is equal to the specified value. More...
pa_volume_t | pa_sw_volume_multiply (pa_volume_t a, pa_volume_t b) PA_GCC_CONST
| Multiply two volume specifications, return the result. More...
pa_cvolume * | pa_sw_cvolume_multiply (pa_cvolume *dest, const pa_cvolume *a, const pa_cvolume *b)
| Multiply two per-channel volumes and return the result in *dest. More...
pa_cvolume * | pa_sw_cvolume_multiply_scalar (pa_cvolume *dest, const pa_cvolume *a, pa_volume_t b)
| Multiply a per-channel volume with a scalar volume and return the result in *dest. More...
pa_volume_t | pa_sw_volume_divide (pa_volume_t a, pa_volume_t b) PA_GCC_CONST
| Divide two volume specifications, return the result. More...
pa_cvolume * | pa_sw_cvolume_divide (pa_cvolume *dest, const pa_cvolume *a, const pa_cvolume *b)
| Divide two per-channel volumes and return the result in *dest. More...
pa_cvolume * | pa_sw_cvolume_divide_scalar (pa_cvolume *dest, const pa_cvolume *a, pa_volume_t b)
| Divide a per-channel volume by a scalar volume and return the result in *dest. More...
pa_volume_t | pa_sw_volume_from_dB (double f) PA_GCC_CONST
| Convert a decibel value to a volume (amplitude, not power). More...
double | pa_sw_volume_to_dB (pa_volume_t v) PA_GCC_CONST
| Convert a volume to a decibel value (amplitude, not power). More...
pa_volume_t | pa_sw_volume_from_linear (double v) PA_GCC_CONST
| Convert a linear factor to a volume. More...
double | pa_sw_volume_to_linear (pa_volume_t v) PA_GCC_CONST
| Convert a volume to a linear factor. More...
pa_cvolume * | pa_cvolume_remap (pa_cvolume *v, const pa_channel_map *from, const pa_channel_map *to)
| Remap a volume from one channel mapping to a different channel mapping. More...
int | pa_cvolume_compatible (const pa_cvolume *v, const pa_sample_spec *ss) PA_GCC_PURE
| Return non-zero if the specified volume is compatible with the specified sample spec. More...
int | pa_cvolume_compatible_with_channel_map (const pa_cvolume *v, const pa_channel_map *cm) PA_GCC_PURE
| Return non-zero if the specified volume is compatible with the specified sample spec. More...
float | pa_cvolume_get_balance (const pa_cvolume *v, const pa_channel_map *map) PA_GCC_PURE
| Calculate a 'balance' value for the specified volume with the specified channel map. More...
pa_cvolume * | pa_cvolume_set_balance (pa_cvolume *v, const pa_channel_map *map, float new_balance)
| Adjust the 'balance' value for the specified volume with the specified channel map. More...
float | pa_cvolume_get_fade (const pa_cvolume *v, const pa_channel_map *map) PA_GCC_PURE
| Calculate a 'fade' value (i.e. 'balance' between front and rear) for the specified volume with the specified channel map. More...
pa_cvolume * | pa_cvolume_set_fade (pa_cvolume *v, const pa_channel_map *map, float new_fade)
| Adjust the 'fade' value (i.e. 'balance' between front and rear) for the specified volume with the specified channel map. More...
float | pa_cvolume_get_lfe_balance (const pa_cvolume *v, const pa_channel_map *map) PA_GCC_PURE
| Calculate a 'lfe balance' value for the specified volume with the specified channel map. More...
pa_cvolume * | pa_cvolume_set_lfe_balance (pa_cvolume *v, const pa_channel_map *map, float new_balance)
| Adjust the 'lfe balance' value for the specified volume with the specified channel map. More...
pa_cvolume * | pa_cvolume_scale (pa_cvolume *v, pa_volume_t max)
| Scale the passed pa_cvolume structure so that the maximum volume of all channels equals max. More...
pa_cvolume * | pa_cvolume_scale_mask (pa_cvolume *v, pa_volume_t max, const pa_channel_map *cm, pa_channel_position_mask_t mask)
| Scale the passed pa_cvolume structure so that the maximum volume of all channels selected via cm/mask equals max. More...
pa_cvolume * | pa_cvolume_set_position (pa_cvolume *cv, const pa_channel_map *map, pa_channel_position_t t, pa_volume_t v)
| Set the passed volume to all channels at the specified channel position. More...
pa_volume_t | pa_cvolume_get_position (const pa_cvolume *cv, const pa_channel_map *map, pa_channel_position_t t) PA_GCC_PURE
| Get the maximum volume of all channels at the specified channel position. More...
pa_cvolume * | pa_cvolume_merge (pa_cvolume *dest, const pa_cvolume *a, const pa_cvolume *b)
| This goes through all channels in a and b and sets the corresponding channel in dest to the greater volume of both. More...
pa_cvolume * | pa_cvolume_inc_clamp (pa_cvolume *v, pa_volume_t inc, pa_volume_t limit)
| Increase the volume passed in by 'inc', but not exceeding 'limit'. More...
pa_cvolume * | pa_cvolume_inc (pa_cvolume *v, pa_volume_t inc)
| Increase the volume passed in by 'inc'. More...
pa_cvolume * | pa_cvolume_dec (pa_cvolume *v, pa_volume_t dec)
| Decrease the volume passed in by 'dec'. More...

## Detailed Description

Constants and routines for volume handling.

See also Volume Control

## Macro Definition Documentation

## ◆ PA_CLAMP_VOLUME

#define PA_CLAMP_VOLUME | ( |  | v | ) | (PA_CLAMP_UNLIKELY((v), PA_VOLUME_MUTED, PA_VOLUME_MAX))

Clamp volume to the permitted range.

Since
  1.0

## ◆ pa_cvolume_is_muted

#define pa_cvolume_is_muted | ( |  | a | ) | pa_cvolume_channels_equal_to((a), PA_VOLUME_MUTED)

Return 1 if the specified volume has all channels muted.

## ◆ pa_cvolume_is_norm

#define pa_cvolume_is_norm | ( |  | a | ) | pa_cvolume_channels_equal_to((a), PA_VOLUME_NORM)

Return 1 if the specified volume has all channels on normal level.

## ◆ pa_cvolume_mute

#define pa_cvolume_mute | ( |  | a,
|  |  | n
| ) |  | pa_cvolume_set((a), (n), PA_VOLUME_MUTED)

Set the volume of the first n channels to PA_VOLUME_MUTED.

## ◆ pa_cvolume_reset

#define pa_cvolume_reset | ( |  | a,
|  |  | n
| ) |  | pa_cvolume_set((a), (n), PA_VOLUME_NORM)

Set the volume of the first n channels to PA_VOLUME_NORM.

## ◆ PA_CVOLUME_SNPRINT_MAX

#define PA_CVOLUME_SNPRINT_MAX 320

Maximum length of the strings returned by pa_cvolume_snprint().

Please note that this value can change with any release without warning and without being considered API or ABI breakage. You should not use this definition anywhere where it might become part of an ABI.

## ◆ PA_CVOLUME_SNPRINT_VERBOSE_MAX

#define PA_CVOLUME_SNPRINT_VERBOSE_MAX 1984

Maximum length of the strings returned by pa_cvolume_snprint_verbose().

Please note that this value can change with any release without warning and without being considered API or ABI breakage. You should not use this definition anywhere where it might become part of an ABI.

Since
  5.0

## ◆ PA_DECIBEL_MININFTY

#define PA_DECIBEL_MININFTY ((double) -200.0)

This floor value is used as minus infinity when using pa_sw_volume_to_dB() / pa_sw_volume_from_dB().

## ◆ PA_SW_CVOLUME_SNPRINT_DB_MAX

#define PA_SW_CVOLUME_SNPRINT_DB_MAX 448

Maximum length of the strings returned by pa_sw_cvolume_snprint_dB().

Please note that this value can change with any release without warning and without being considered API or ABI breakage. You should not use this definition anywhere where it might become part of an ABI.

Since
  0.9.13

## ◆ PA_SW_VOLUME_SNPRINT_DB_MAX

#define PA_SW_VOLUME_SNPRINT_DB_MAX 11

Maximum length of the strings returned by pa_sw_volume_snprint_dB().

Please note that this value can change with any release without warning and without being considered API or ABI breakage. You should not use this definition anywhere where it might become part of an ABI.

Since
  0.9.15

## ◆ PA_VOLUME_INVALID

#define PA_VOLUME_INVALID ((pa_volume_t) UINT32_MAX)

Special 'invalid' volume.

Since
  0.9.16

## ◆ PA_VOLUME_IS_VALID

#define PA_VOLUME_IS_VALID | ( |  | v | ) | ((v) <= PA_VOLUME_MAX)

Check if volume is valid.

Since
  1.0

## ◆ PA_VOLUME_MAX

#define PA_VOLUME_MAX ((pa_volume_t) UINT32_MAX/2)

Maximum valid volume we can store.

Since
  0.9.15

## ◆ PA_VOLUME_MUTED

#define PA_VOLUME_MUTED ((pa_volume_t) 0U)

Muted (minimal valid) volume (0%, -inf dB)

## ◆ PA_VOLUME_NORM

#define PA_VOLUME_NORM ((pa_volume_t) 0x10000U)

Normal volume (100%, 0 dB)

## ◆ PA_VOLUME_SNPRINT_MAX

#define PA_VOLUME_SNPRINT_MAX 10

Maximum length of the strings returned by pa_volume_snprint().

Please note that this value can change with any release without warning and without being considered API or ABI breakage. You should not use this definition anywhere where it might become part of an ABI.

Since
  0.9.15

## ◆ PA_VOLUME_SNPRINT_VERBOSE_MAX

#define PA_VOLUME_SNPRINT_VERBOSE_MAX 35

Maximum length of the strings returned by pa_volume_snprint_verbose().

Please note that this value can change with any release without warning and withou being considered API or ABI breakage. You should not use this definition anywhere where it might become part of an ABI.

Since
  5.0

## ◆ PA_VOLUME_UI_MAX

#define PA_VOLUME_UI_MAX (pa_sw_volume_from_dB(+11.0))

Recommended maximum volume to show in user facing UIs.

Note: UIs should deal gracefully with volumes greater than this value and not cause feedback loops etc. - i.e. if the volume is more than this, the UI should not limit it and push the limited value back to the server.

Since
  0.9.23

## Typedef Documentation

## ◆ pa_cvolume

typedef struct pa_cvolume pa_cvolume

A structure encapsulating a per-channel volume.

## ◆ pa_volume_t

typedef uint32_t pa_volume_t

Volume specification: PA_VOLUME_MUTED: silence; < PA_VOLUME_NORM: decreased volume; PA_VOLUME_NORM: normal volume;

> ‍PA_VOLUME_NORM: increased volume

## Function Documentation

## ◆ pa_cvolume_avg()

pa_volume_t pa_cvolume_avg | ( | const pa_cvolume * | a | ) |

Return the average volume of all channels.

## ◆ pa_cvolume_avg_mask()

pa_volume_t pa_cvolume_avg_mask | ( | const pa_cvolume * | a,
|  | const pa_channel_map * | cm,
|  | pa_channel_position_mask_t | mask
| ) |  |

Return the average volume of all channels that are included in the specified channel map with the specified channel position mask.

If cm is NULL this call is identical to pa_cvolume_avg(). If no channel is selected the returned value will be PA_VOLUME_MUTED.

Since
  0.9.16

## ◆ pa_cvolume_channels_equal_to()

int pa_cvolume_channels_equal_to | ( | const pa_cvolume * | a,
|  | pa_volume_t | v
| ) |  |

Return non-zero if the volume of all channels is equal to the specified value.

## ◆ pa_cvolume_compatible()

int pa_cvolume_compatible | ( | const pa_cvolume * | v,
|  | const pa_sample_spec * | ss
| ) |  |

Return non-zero if the specified volume is compatible with the specified sample spec.

Since
  0.9.13

## ◆ pa_cvolume_compatible_with_channel_map()

int pa_cvolume_compatible_with_channel_map | ( | const pa_cvolume * | v,
|  | const pa_channel_map * | cm
| ) |  |

Return non-zero if the specified volume is compatible with the specified sample spec.

Since
  0.9.15

## ◆ pa_cvolume_dec()

pa_cvolume * pa_cvolume_dec | ( | pa_cvolume * | v,
|  | pa_volume_t | dec
| ) |  |

Decrease the volume passed in by 'dec'.

The proportions between the channels are kept. Returns v, or NULL on error.

Since
  0.9.16

## ◆ pa_cvolume_equal()

int pa_cvolume_equal | ( | const pa_cvolume * | a,
|  | const pa_cvolume * | b
| ) |  |

Return non-zero when *a == *b, checking that both a and b have the same number of channels and that the volumes of channels in a equal those in b.

## ◆ pa_cvolume_get_balance()

float pa_cvolume_get_balance | ( | const pa_cvolume * | v,
|  | const pa_channel_map * | map
| ) |  |

Calculate a 'balance' value for the specified volume with the specified channel map.

The return value will range from -1.0f (left) to +1.0f (right). If no balance value is applicable to this channel map the return value will always be 0.0f. See pa_channel_map_can_balance().

Since
  0.9.15

## ◆ pa_cvolume_get_fade()

float pa_cvolume_get_fade | ( | const pa_cvolume * | v,
|  | const pa_channel_map * | map
| ) |  |

Calculate a 'fade' value (i.e. 'balance' between front and rear) for the specified volume with the specified channel map.

The return value will range from -1.0f (rear) to +1.0f (left). If no fade value is applicable to this channel map the return value will always be 0.0f. See pa_channel_map_can_fade().

Since
  0.9.15

## ◆ pa_cvolume_get_lfe_balance()

float pa_cvolume_get_lfe_balance | ( | const pa_cvolume * | v,
|  | const pa_channel_map * | map
| ) |  |

Calculate a 'lfe balance' value for the specified volume with the specified channel map.

The return value will range from -1.0f (no lfe) to +1.0f (only lfe), where 0.0f is balanced. If no value is applicable to this channel map the return value will always be 0.0f. See pa_channel_map_can_lfe_balance().

Since
  8.0

## ◆ pa_cvolume_get_position()

pa_volume_t pa_cvolume_get_position | ( | const pa_cvolume * | cv,
|  | const pa_channel_map * | map,
|  | pa_channel_position_t | t
| ) |  |

Get the maximum volume of all channels at the specified channel position.

Will return 0 if there is no channel at the position specified. You can check if a channel map includes a specific position by calling pa_channel_map_has_position().

Since
  0.9.16

## ◆ pa_cvolume_inc()

pa_cvolume * pa_cvolume_inc | ( | pa_cvolume * | v,
|  | pa_volume_t | inc
| ) |  |

Increase the volume passed in by 'inc'.

The proportions between the channels are kept. Returns v, or NULL on error.

Since
  0.9.16

## ◆ pa_cvolume_inc_clamp()

pa_cvolume * pa_cvolume_inc_clamp | ( | pa_cvolume * | v,
|  | pa_volume_t | inc,
|  | pa_volume_t | limit
| ) |  |

Increase the volume passed in by 'inc', but not exceeding 'limit'.

The proportions between the channels are kept. Returns v, or NULL on error.

Since
  0.9.19

## ◆ pa_cvolume_init()

pa_cvolume * pa_cvolume_init | ( | pa_cvolume * | a | ) |

Initialize the specified volume and return a pointer to it.

The sample spec will have a defined state but pa_cvolume_valid() will fail for it.

Since
  0.9.13

## ◆ pa_cvolume_max()

pa_volume_t pa_cvolume_max | ( | const pa_cvolume * | a | ) |

Return the maximum volume of all channels.

Since
  0.9.12

## ◆ pa_cvolume_max_mask()

pa_volume_t pa_cvolume_max_mask | ( | const pa_cvolume * | a,
|  | const pa_channel_map * | cm,
|  | pa_channel_position_mask_t | mask
| ) |  |

Return the maximum volume of all channels that are included in the specified channel map with the specified channel position mask.

If cm is NULL this call is identical to pa_cvolume_max(). If no channel is selected the returned value will be PA_VOLUME_MUTED.

Since
  0.9.16

## ◆ pa_cvolume_merge()

pa_cvolume * pa_cvolume_merge | ( | pa_cvolume * | dest,
|  | const pa_cvolume * | a,
|  | const pa_cvolume * | b
| ) |  |

This goes through all channels in a and b and sets the corresponding channel in dest to the greater volume of both.

a, b and dest may point to the same structure. Returns dest, or NULL on error.

Since
  0.9.16

## ◆ pa_cvolume_min()

pa_volume_t pa_cvolume_min | ( | const pa_cvolume * | a | ) |

Return the minimum volume of all channels.

Since
  0.9.16

## ◆ pa_cvolume_min_mask()

pa_volume_t pa_cvolume_min_mask | ( | const pa_cvolume * | a,
|  | const pa_channel_map * | cm,
|  | pa_channel_position_mask_t | mask
| ) |  |

Return the minimum volume of all channels that are included in the specified channel map with the specified channel position mask.

If cm is NULL this call is identical to pa_cvolume_min(). If no channel is selected the returned value will be PA_VOLUME_MUTED.

Since
  0.9.16

## ◆ pa_cvolume_remap()

pa_cvolume * pa_cvolume_remap | ( | pa_cvolume * | v,
|  | const pa_channel_map * | from,
|  | const pa_channel_map * | to
| ) |  |

Remap a volume from one channel mapping to a different channel mapping.

Returns v.

Since
  0.9.12

## ◆ pa_cvolume_scale()

pa_cvolume * pa_cvolume_scale | ( | pa_cvolume * | v,
|  | pa_volume_t | max
| ) |  |

Scale the passed pa_cvolume structure so that the maximum volume of all channels equals max.

The proportions between the channel volumes are kept. Returns v, or NULL on error.

Since
  0.9.15

## ◆ pa_cvolume_scale_mask()

pa_cvolume * pa_cvolume_scale_mask | ( | pa_cvolume * | v,
|  | pa_volume_t | max,
|  | const pa_channel_map * | cm,
|  | pa_channel_position_mask_t | mask
| ) |  |

Scale the passed pa_cvolume structure so that the maximum volume of all channels selected via cm/mask equals max.

This also modifies the volume of those channels that are unmasked. The proportions between the channel volumes are kept. If cm is NULL this call is identical to pa_cvolume_scale(). Returns v, or NULL on error.

Since
  0.9.16

## ◆ pa_cvolume_set()

pa_cvolume * pa_cvolume_set | ( | pa_cvolume * | a,
|  | unsigned | channels,
|  | pa_volume_t | v
| ) |  |

Set the volume of the specified number of channels to the volume v.

## ◆ pa_cvolume_set_balance()

pa_cvolume * pa_cvolume_set_balance | ( | pa_cvolume * | v,
|  | const pa_channel_map * | map,
|  | float | new_balance
| ) |  |

Adjust the 'balance' value for the specified volume with the specified channel map.

v will be modified in place and returned. The balance is a value between -1.0f and +1.0f. This operation might not be reversible! Also, after this call pa_cvolume_get_balance() is not guaranteed to actually return the requested balance value (e.g. when the input volume was zero anyway for all channels). If no balance value is applicable to this channel map the volume will not be modified. See pa_channel_map_can_balance(). Will return NULL on error.

Since
  0.9.15

## ◆ pa_cvolume_set_fade()

pa_cvolume * pa_cvolume_set_fade | ( | pa_cvolume * | v,
|  | const pa_channel_map * | map,
|  | float | new_fade
| ) |  |

Adjust the 'fade' value (i.e. 'balance' between front and rear) for the specified volume with the specified channel map.

v will be modified in place and returned. The balance is a value between -1.0f and +1.0f. This operation might not be reversible! Also, after this call pa_cvolume_get_fade() is not guaranteed to actually return the requested fade value (e.g. when the input volume was zero anyway for all channels). If no fade value is applicable to this channel map the volume will not be modified. See pa_channel_map_can_fade(). Will return NULL on error.

Since
  0.9.15

## ◆ pa_cvolume_set_lfe_balance()

pa_cvolume * pa_cvolume_set_lfe_balance | ( | pa_cvolume * | v,
|  | const pa_channel_map * | map,
|  | float | new_balance
| ) |  |

Adjust the 'lfe balance' value for the specified volume with the specified channel map.

v will be modified in place and returned. The balance is a value between -1.0f (no lfe) and +1.0f (only lfe). This operation might not be reversible! Also, after this call pa_cvolume_get_lfe_balance() is not guaranteed to actually return the requested value (e.g. when the input volume was zero anyway for all channels). If no lfe balance value is applicable to this channel map the volume will not be modified. See pa_channel_map_can_lfe_balance(). Will return NULL on error.

Since
  8.0

## ◆ pa_cvolume_set_position()

pa_cvolume * pa_cvolume_set_position | ( | pa_cvolume * | cv,
|  | const pa_channel_map * | map,
|  | pa_channel_position_t | t,
|  | pa_volume_t | v
| ) |  |

Set the passed volume to all channels at the specified channel position.

Will return the updated volume struct, or NULL if there is no channel at the position specified. You can check if a channel map includes a specific position by calling pa_channel_map_has_position(). Returns cv, or NULL on error.

Since
  0.9.16

## ◆ pa_cvolume_snprint()

char * pa_cvolume_snprint | ( | char * | s,
|  | size_t | l,
|  | const pa_cvolume * | c
| ) |  |

Pretty print a volume structure.

Returns s.

## ◆ pa_cvolume_snprint_verbose()

char * pa_cvolume_snprint_verbose | ( | char * | s,
|  | size_t | l,
|  | const pa_cvolume * | c,
|  | const pa_channel_map * | map,
|  | int | print_dB
| ) |  |

Pretty print a volume structure in a verbose way.

The volume for each channel is printed in several formats: the raw pa_volume_t value, percentage, and if print_dB is non-zero, also the dB value. If map is not NULL, the channel names will be printed. Returns s.

Since
  5.0

## ◆ pa_cvolume_valid()

int pa_cvolume_valid | ( | const pa_cvolume * | v | ) |

Return non-zero when the passed cvolume structure is valid.

## ◆ pa_sw_cvolume_divide()

pa_cvolume * pa_sw_cvolume_divide | ( | pa_cvolume * | dest,
|  | const pa_cvolume * | a,
|  | const pa_cvolume * | b
| ) |  |

Divide two per-channel volumes and return the result in *dest.

This is only valid for software volumes! a, b and dest may point to the same structure. Returns dest, or NULL on error.

Since
  0.9.13

## ◆ pa_sw_cvolume_divide_scalar()

pa_cvolume * pa_sw_cvolume_divide_scalar | ( | pa_cvolume * | dest,
|  | const pa_cvolume * | a,
|  | pa_volume_t | b
| ) |  |

Divide a per-channel volume by a scalar volume and return the result in *dest.

This is only valid for software volumes! a and dest may point to the same structure. Returns dest, or NULL on error.

Since
  0.9.16

## ◆ pa_sw_cvolume_multiply()

pa_cvolume * pa_sw_cvolume_multiply | ( | pa_cvolume * | dest,
|  | const pa_cvolume * | a,
|  | const pa_cvolume * | b
| ) |  |

Multiply two per-channel volumes and return the result in *dest.

This is only valid for software volumes! a, b and dest may point to the same structure. Returns dest, or NULL on error.

## ◆ pa_sw_cvolume_multiply_scalar()

pa_cvolume * pa_sw_cvolume_multiply_scalar | ( | pa_cvolume * | dest,
|  | const pa_cvolume * | a,
|  | pa_volume_t | b
| ) |  |

Multiply a per-channel volume with a scalar volume and return the result in *dest.

This is only valid for software volumes! a and dest may point to the same structure. Returns dest, or NULL on error.

Since
  0.9.16

## ◆ pa_sw_cvolume_snprint_dB()

char * pa_sw_cvolume_snprint_dB | ( | char * | s,
|  | size_t | l,
|  | const pa_cvolume * | c
| ) |  |

Pretty print a volume structure, showing dB values.

Returns s.

Since
  0.9.13

## ◆ pa_sw_volume_divide()

pa_volume_t pa_sw_volume_divide | ( | pa_volume_t | a,
|  | pa_volume_t | b
| ) |  |

Divide two volume specifications, return the result.

This uses PA_VOLUME_NORM as neutral element of division. This is only valid for software volumes! If a division by zero is tried the result will be 0.

Since
  0.9.13

## ◆ pa_sw_volume_from_dB()

pa_volume_t pa_sw_volume_from_dB | ( | double | f | ) |

Convert a decibel value to a volume (amplitude, not power).

This is only valid for software volumes!

## ◆ pa_sw_volume_from_linear()

pa_volume_t pa_sw_volume_from_linear | ( | double | v | ) |

Convert a linear factor to a volume.

0.0 and less is muted while 1.0 is PA_VOLUME_NORM. This is only valid for software volumes!

## ◆ pa_sw_volume_multiply()

pa_volume_t pa_sw_volume_multiply | ( | pa_volume_t | a,
|  | pa_volume_t | b
| ) |  |

Multiply two volume specifications, return the result.

This uses PA_VOLUME_NORM as neutral element of multiplication. This is only valid for software volumes!

## ◆ pa_sw_volume_snprint_dB()

char * pa_sw_volume_snprint_dB | ( | char * | s,
|  | size_t | l,
|  | pa_volume_t | v
| ) |  |

Pretty print a volume but show dB values.

Returns s.

Since
  0.9.15

## ◆ pa_sw_volume_to_dB()

double pa_sw_volume_to_dB | ( | pa_volume_t | v | ) |

Convert a volume to a decibel value (amplitude, not power).

This is only valid for software volumes!

## ◆ pa_sw_volume_to_linear()

double pa_sw_volume_to_linear | ( | pa_volume_t | v | ) |

Convert a volume to a linear factor.

This is only valid for software volumes!

## ◆ pa_volume_snprint()

char * pa_volume_snprint | ( | char * | s,
|  | size_t | l,
|  | pa_volume_t | v
| ) |  |

Pretty print a volume.

Returns s.

Since
  0.9.15

## ◆ pa_volume_snprint_verbose()

char * pa_volume_snprint_verbose | ( | char * | s,
|  | size_t | l,
|  | pa_volume_t | v,
|  | int | print_dB
| ) |  |

Pretty print a volume in a verbose way.

The volume is printed in several formats: the raw pa_volume_t value, percentage, and if print_dB is non-zero, also the dB value. Returns s.

Since
  5.0