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...
Defines
#define	PA_VOLUME_NORM   ((pa_volume_t) 0x10000U)
	Normal volume (100%, 0 dB).
#define	PA_VOLUME_MUTED   ((pa_volume_t) 0U)
	Muted volume (0%, -inf dB).
#define	PA_VOLUME_MAX   ((pa_volume_t) UINT32_MAX)
	Maximum volume we can store.
#define	pa_cvolume_reset(a, n)   pa_cvolume_set((a), (n), PA_VOLUME_NORM)
	Set the volume of all channels to PA_VOLUME_NORM.
#define	pa_cvolume_mute(a, n)   pa_cvolume_set((a), (n), PA_VOLUME_MUTED)
	Set the volume of all channels to PA_VOLUME_MUTED.
#define	PA_CVOLUME_SNPRINT_MAX   320
	Maximum length of the strings returned by pa_cvolume_snprint().
#define	PA_SW_CVOLUME_SNPRINT_DB_MAX   448
	Maximum length of the strings returned by pa_cvolume_snprint_dB().
#define	PA_VOLUME_SNPRINT_MAX   10
	Maximum length of the strings returned by pa_volume_snprint().
#define	PA_SW_VOLUME_SNPRINT_DB_MAX   10
	Maximum length of the strings returned by pa_volume_snprint_dB().
#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.
#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.
#define	PA_DECIBEL_MININFTY   ((double) -200.0)
	This floor value is used as minus infinity when using pa_volume_{to,from}_dB().
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.
Functions
int	pa_cvolume_equal (const pa_cvolume *a, const pa_cvolume *b) PA_GCC_PURE
	Return non-zero when *a == *b.
pa_cvolume *	pa_cvolume_init (pa_cvolume *a)
	Initialize the specified volume and return a pointer to it.
pa_cvolume *	pa_cvolume_set (pa_cvolume *a, unsigned channels, pa_volume_t v)
	Set the volume of all channels to the specified parameter.
char *	pa_cvolume_snprint (char *s, size_t l, const pa_cvolume *c)
	Pretty print a volume structure.
char *	pa_sw_cvolume_snprint_dB (char *s, size_t l, const pa_cvolume *c)
	Pretty print a volume structure but show dB values.
char *	pa_volume_snprint (char *s, size_t l, pa_volume_t v)
	Pretty print a volume.
char *	pa_sw_volume_snprint_dB (char *s, size_t l, pa_volume_t v)
	Pretty print a volume but show dB values.
pa_volume_t	pa_cvolume_avg (const pa_cvolume *a) PA_GCC_PURE
	Return the average volume of all channels.
pa_volume_t	pa_cvolume_max (const pa_cvolume *a) PA_GCC_PURE
	Return the maximum volume of all channels.
int	pa_cvolume_valid (const pa_cvolume *v) PA_GCC_PURE
	Return TRUE when the passed cvolume structure is valid, FALSE otherwise.
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.
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.
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.
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.
pa_cvolume *	pa_sw_cvolume_divide (pa_cvolume *dest, const pa_cvolume *a, const pa_cvolume *b)
	Multiply to per-channel volumes and return the result in *dest.
pa_volume_t	pa_sw_volume_from_dB (double f) PA_GCC_CONST
	Convert a decibel value to a volume (amplitude, not power).
double	pa_sw_volume_to_dB (pa_volume_t v) PA_GCC_CONST
	Convert a volume to a decibel value (amplitude, not power).
pa_volume_t	pa_sw_volume_from_linear (double v) PA_GCC_CONST
	Convert a linear factor to a volume.
double	pa_sw_volume_to_linear (pa_volume_t v) PA_GCC_CONST
	Convert a volume to a linear factor.
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.
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.
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.
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.
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.
float	pa_cvolume_get_fade (const pa_cvolume *v, const pa_channel_map *map) PA_GCC_PURE
	Calculate a 'fade' value (i.e.
pa_cvolume *	pa_cvolume_set_fade (pa_cvolume *v, const pa_channel_map *map, float new_fade)
	Adjust the 'fade' value (i.e.
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.

---

Detailed Description

Constants and routines for volume handling.

---

Define Documentation

#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.

#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.

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

Set the volume of all channels to PA_VOLUME_MUTED.

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

Set the volume of all channels to PA_VOLUME_NORM.

#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.

#define PA_DECIBEL_MININFTY   ((double) -200.0)

This floor value is used as minus infinity when using pa_volume_{to,from}_dB().

#define PA_SW_CVOLUME_SNPRINT_DB_MAX   448

Maximum length of the strings returned by pa_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

#define PA_SW_VOLUME_SNPRINT_DB_MAX   10

Maximum length of the strings returned by pa_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

#define PA_VOLUME_MAX   ((pa_volume_t) UINT32_MAX)

Maximum volume we can store.

Since:

0.9.15

#define PA_VOLUME_MUTED   ((pa_volume_t) 0U)

Muted volume (0%, -inf dB).

#define PA_VOLUME_NORM   ((pa_volume_t) 0x10000U)

Normal volume (100%, 0 dB).

Examples:

pacat.c, and paplay.c.

#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

---

Typedef Documentation

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.

Examples:

pacat.c, and paplay.c.

---

Function Documentation

pa_volume_t pa_cvolume_avg

(

const pa_cvolume *

a

)

Return the average volume of all channels.

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.

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

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

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

Return non-zero when *a == *b.

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

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* 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_volume_t pa_cvolume_max

(

const pa_cvolume *

a

)

Return the maximum volume of all channels.

Since:

0.9.12

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.

Since:

0.9.12

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.

Since:

0.9.15

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

Set the volume of all channels to the specified parameter.

Examples:

pacat.c, and paplay.c.

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().

Since:

0.9.15

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().

Since:

0.9.15

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

Pretty print a volume structure.

int pa_cvolume_valid

(

const pa_cvolume *

v

)

Return TRUE when the passed cvolume structure is valid, FALSE otherwise.

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

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

This is only valid for software volumes!

Since:

0.9.13

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!

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

Pretty print a volume structure but show dB values.

Since:

0.9.13

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_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_volume_t pa_sw_volume_from_linear

(

double

v

)

Convert a linear factor to a volume.

This is only valid for software volumes!

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!

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

Pretty print a volume but show dB values.

Since:

0.9.15

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!

double pa_sw_volume_to_linear

(

pa_volume_t

v

)

Convert a volume to a linear factor.

This is only valid for software volumes!

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

Pretty print a volume.

Since:

0.9.15