PulseAudio 16.1

Macros | Typedefs | Enumerations | Functions
proplist.h File Reference

Property list constants and functions. More...

Go to the source code of this file.

## Macros
#define | PA_PROP_MEDIA_NAME "media.name"
| For streams: localized media name, formatted as UTF-8. More...
#define | PA_PROP_MEDIA_TITLE "media.title"
| For streams: localized media title if applicable, formatted as UTF-8. More...
#define | PA_PROP_MEDIA_ARTIST "media.artist"
| For streams: localized media artist if applicable, formatted as UTF-8. More...
#define | PA_PROP_MEDIA_COPYRIGHT "media.copyright"
| For streams: localized media copyright string if applicable, formatted as UTF-8. More...
#define | PA_PROP_MEDIA_SOFTWARE "media.software"
| For streams: localized media generator software string if applicable, formatted as UTF-8. More...
#define | PA_PROP_MEDIA_LANGUAGE "media.language"
| For streams: media language if applicable, in standard POSIX format. More...
#define | PA_PROP_MEDIA_FILENAME "media.filename"
| For streams: source filename if applicable, in URI format or local path. More...
#define | PA_PROP_MEDIA_ICON_NAME "media.icon_name"
| For streams: an XDG icon name for the media. More...
#define | PA_PROP_MEDIA_ROLE "media.role"
| For streams: logic role of this media. More...
#define | PA_PROP_FILTER_WANT "filter.want"
| For streams: the name of a filter that is desired, e.g. "echo-cancel" or "equalizer-sink". More...
#define | PA_PROP_FILTER_APPLY "filter.apply"
| For streams: the name of a filter that is desired, e.g. "echo-cancel" or "equalizer-sink". More...
#define | PA_PROP_FILTER_SUPPRESS "filter.suppress"
| For streams: the name of a filter that should specifically suppressed (i.e. overrides PA_PROP_FILTER_WANT). More...
#define | PA_PROP_EVENT_ID "event.id"
| For event sound streams: XDG event sound name. More...
#define | PA_PROP_EVENT_DESCRIPTION "event.description"
| For event sound streams: localized human readable one-line description of the event, formatted as UTF-8. More...
#define | PA_PROP_EVENT_MOUSE_X "event.mouse.x"
| For event sound streams: absolute horizontal mouse position on the screen if the event sound was triggered by a mouse click, integer formatted as text string. More...
#define | PA_PROP_EVENT_MOUSE_Y "event.mouse.y"
| For event sound streams: absolute vertical mouse position on the screen if the event sound was triggered by a mouse click, integer formatted as text string. More...
#define | PA_PROP_EVENT_MOUSE_HPOS "event.mouse.hpos"
| For event sound streams: relative horizontal mouse position on the screen if the event sound was triggered by a mouse click, float formatted as text string, ranging from 0.0 (left side of the screen) to 1.0 (right side of the screen). More...
#define | PA_PROP_EVENT_MOUSE_VPOS "event.mouse.vpos"
| For event sound streams: relative vertical mouse position on the screen if the event sound was triggered by a mouse click, float formatted as text string, ranging from 0.0 (top of the screen) to 1.0 (bottom of the screen). More...
#define | PA_PROP_EVENT_MOUSE_BUTTON "event.mouse.button"
| For event sound streams: mouse button that triggered the event if applicable, integer formatted as string with 0=left, 1=middle, 2=right. More...
#define | PA_PROP_WINDOW_NAME "window.name"
| For streams that belong to a window on the screen: localized window title. More...
#define | PA_PROP_WINDOW_ID "window.id"
| For streams that belong to a window on the screen: a textual id for identifying a window logically. More...
#define | PA_PROP_WINDOW_ICON_NAME "window.icon_name"
| For streams that belong to a window on the screen: an XDG icon name for the window. More...
#define | PA_PROP_WINDOW_X "window.x"
| For streams that belong to a window on the screen: absolute horizontal window position on the screen, integer formatted as text string. More...
#define | PA_PROP_WINDOW_Y "window.y"
| For streams that belong to a window on the screen: absolute vertical window position on the screen, integer formatted as text string. More...
#define | PA_PROP_WINDOW_WIDTH "window.width"
| For streams that belong to a window on the screen: window width on the screen, integer formatted as text string. More...
#define | PA_PROP_WINDOW_HEIGHT "window.height"
| For streams that belong to a window on the screen: window height on the screen, integer formatted as text string. More...
#define | PA_PROP_WINDOW_HPOS "window.hpos"
| For streams that belong to a window on the screen: relative position of the window center on the screen, float formatted as text string, ranging from 0.0 (left side of the screen) to 1.0 (right side of the screen). More...
#define | PA_PROP_WINDOW_VPOS "window.vpos"
| For streams that belong to a window on the screen: relative position of the window center on the screen, float formatted as text string, ranging from 0.0 (top of the screen) to 1.0 (bottom of the screen). More...
#define | PA_PROP_WINDOW_DESKTOP "window.desktop"
| For streams that belong to a window on the screen: if the windowing system supports multiple desktops, a comma separated list of indexes of the desktops this window is visible on. More...
#define | PA_PROP_WINDOW_X11_DISPLAY "window.x11.display"
| For streams that belong to an X11 window on the screen: the X11 display string. More...
#define | PA_PROP_WINDOW_X11_SCREEN "window.x11.screen"
| For streams that belong to an X11 window on the screen: the X11 screen the window is on, an integer formatted as string. More...
#define | PA_PROP_WINDOW_X11_MONITOR "window.x11.monitor"
| For streams that belong to an X11 window on the screen: the X11 monitor the window is on, an integer formatted as string. More...
#define | PA_PROP_WINDOW_X11_XID "window.x11.xid"
| For streams that belong to an X11 window on the screen: the window XID, an integer formatted as string. More...
#define | PA_PROP_APPLICATION_NAME "application.name"
| For clients/streams: localized human readable application name. More...
#define | PA_PROP_APPLICATION_ID "application.id"
| For clients/streams: a textual id for identifying an application logically. More...
#define | PA_PROP_APPLICATION_VERSION "application.version"
| For clients/streams: a version string, e.g. "0.6.88". More...
#define | PA_PROP_APPLICATION_ICON_NAME "application.icon_name"
| For clients/streams: an XDG icon name for the application. More...
#define | PA_PROP_APPLICATION_LANGUAGE "application.language"
| For clients/streams: application language if applicable, in standard POSIX format. More...
#define | PA_PROP_APPLICATION_PROCESS_ID "application.process.id"
| For clients/streams on UNIX: application process PID, an integer formatted as string. More...
#define | PA_PROP_APPLICATION_PROCESS_BINARY "application.process.binary"
| For clients/streams: application process name. More...
#define | PA_PROP_APPLICATION_PROCESS_USER "application.process.user"
| For clients/streams: application user name. More...
#define | PA_PROP_APPLICATION_PROCESS_HOST "application.process.host"
| For clients/streams: host name the application runs on. More...
#define | PA_PROP_APPLICATION_PROCESS_MACHINE_ID "application.process.machine_id"
| For clients/streams: the D-Bus host id the application runs on. More...
#define | PA_PROP_APPLICATION_PROCESS_SESSION_ID "application.process.session_id"
| For clients/streams: an id for the login session the application runs in. More...
#define | PA_PROP_DEVICE_STRING "device.string"
| For devices: device string in the underlying audio layer's format. More...
#define | PA_PROP_DEVICE_API "device.api"
| For devices: API this device is access with. More...
#define | PA_PROP_DEVICE_DESCRIPTION "device.description"
| For devices: localized human readable device one-line description. More...
#define | PA_PROP_DEVICE_BUS_PATH "device.bus_path"
| For devices: bus path to the device in the OS' format. More...
#define | PA_PROP_DEVICE_SERIAL "device.serial"
| For devices: serial number if applicable. More...
#define | PA_PROP_DEVICE_VENDOR_ID "device.vendor.id"
| For devices: vendor ID if applicable. More...
#define | PA_PROP_DEVICE_VENDOR_NAME "device.vendor.name"
| For devices: vendor name if applicable. More...
#define | PA_PROP_DEVICE_PRODUCT_ID "device.product.id"
| For devices: product ID if applicable. More...
#define | PA_PROP_DEVICE_PRODUCT_NAME "device.product.name"
| For devices: product name if applicable. More...
#define | PA_PROP_DEVICE_CLASS "device.class"
| For devices: device class. More...
#define | PA_PROP_DEVICE_FORM_FACTOR "device.form_factor"
| For devices: form factor if applicable. More...
#define | PA_PROP_DEVICE_BUS "device.bus"
| For devices: bus of the device if applicable. More...
#define | PA_PROP_DEVICE_ICON_NAME "device.icon_name"
| For devices: an XDG icon name for the device. More...
#define | PA_PROP_DEVICE_ACCESS_MODE "device.access_mode"
| For devices: access mode of the device if applicable. More...
#define | PA_PROP_DEVICE_MASTER_DEVICE "device.master_device"
| For filter devices: master device id if applicable. More...
#define | PA_PROP_DEVICE_BUFFERING_BUFFER_SIZE "device.buffering.buffer_size"
| For devices: buffer size in bytes, integer formatted as string. More...
#define | PA_PROP_DEVICE_BUFFERING_FRAGMENT_SIZE "device.buffering.fragment_size"
| For devices: fragment size in bytes, integer formatted as string. More...
#define | PA_PROP_DEVICE_PROFILE_NAME "device.profile.name"
| For devices: profile identifier for the profile this devices is in. More...
#define | PA_PROP_DEVICE_INTENDED_ROLES "device.intended_roles"
| For devices: intended use. More...
#define | PA_PROP_DEVICE_PROFILE_DESCRIPTION "device.profile.description"
| For devices: human readable one-line description of the profile this device is in. More...
#define | PA_PROP_MODULE_AUTHOR "module.author"
| For modules: the author's name, formatted as UTF-8 string. More...
#define | PA_PROP_MODULE_DESCRIPTION "module.description"
| For modules: a human readable one-line description of the module's purpose formatted as UTF-8. More...
#define | PA_PROP_MODULE_USAGE "module.usage"
| For modules: a human readable usage description of the module's arguments formatted as UTF-8. More...
#define | PA_PROP_MODULE_VERSION "module.version"
| For modules: a version string for the module. More...
#define | PA_PROP_FORMAT_SAMPLE_FORMAT "format.sample_format"
| For PCM formats: the sample format used as returned by pa_sample_format_to_string() More...
#define | PA_PROP_FORMAT_RATE "format.rate"
| For all formats: the sample rate (unsigned integer) More...
#define | PA_PROP_FORMAT_CHANNELS "format.channels"
| For all formats: the number of channels (unsigned integer) More...
#define | PA_PROP_FORMAT_CHANNEL_MAP "format.channel_map"
| For PCM formats: the channel map of the stream as returned by pa_channel_map_snprint() More...
#define | PA_PROP_CONTEXT_FORCE_DISABLE_SHM "context.force.disable.shm"
| For context: whether to forcefully disable data transfer via POSIX or memfd shared memory. More...
#define | PA_PROP_BLUETOOTH_CODEC "bluetooth.codec"
| For a bluez device: the currently selected codec name. More...

## Typedefs
typedef struct pa_proplist | pa_proplist
| A property list object. More...
typedef enum pa_update_mode | pa_update_mode_t
| Update mode enum for pa_proplist_update(). More...

## Enumerations
enum | pa_update_mode { PA_UPDATE_SET , PA_UPDATE_MERGE , PA_UPDATE_REPLACE }
| Update mode enum for pa_proplist_update(). More...

## Functions
pa_proplist * | pa_proplist_new (void)
| Allocate a property list. More...
void | pa_proplist_free (pa_proplist *p)
| Free the property list. More...
int | pa_proplist_key_valid (const char *key)
| Returns a non-zero value if the key is valid. More...
int | pa_proplist_sets (pa_proplist *p, const char *key, const char *value)
| Append a new string entry to the property list, possibly overwriting an already existing entry with the same key. More...
int | pa_proplist_setp (pa_proplist *p, const char *pair)
| Append a new string entry to the property list, possibly overwriting an already existing entry with the same key. More...
int | pa_proplist_setf (pa_proplist *p, const char *key, const char *format,...) PA_GCC_PRINTF_ATTR(3
| Append a new string entry to the property list, possibly overwriting an already existing entry with the same key. More...
int int | pa_proplist_set (pa_proplist *p, const char *key, const void *data, size_t nbytes)
| Append a new arbitrary data entry to the property list, possibly overwriting an already existing entry with the same key. More...
const char * | pa_proplist_gets (const pa_proplist *p, const char *key)
| Return a string entry for the specified key. More...
int | pa_proplist_get (const pa_proplist *p, const char *key, const void **data, size_t *nbytes)
| Store the value for the specified key in data. More...
void | pa_proplist_update (pa_proplist *p, pa_update_mode_t mode, const pa_proplist *other)
| Merge property list "other" into "p", adhering the merge mode as specified in "mode". More...
int | pa_proplist_unset (pa_proplist *p, const char *key)
| Removes a single entry from the property list, identified be the specified key name. More...
int | pa_proplist_unset_many (pa_proplist *p, const char *const keys[])
| Similar to pa_proplist_unset() but takes an array of keys to remove. More...
const char * | pa_proplist_iterate (const pa_proplist *p, void **state)
| Iterate through the property list. More...
char * | pa_proplist_to_string (const pa_proplist *p)
| Format the property list nicely as a human readable string. More...
char * | pa_proplist_to_string_sep (const pa_proplist *p, const char *sep)
| Format the property list nicely as a human readable string and choose the separator. More...
pa_proplist * | pa_proplist_from_string (const char *str)
| Allocate a new property list and assign key/value from a human readable string. More...
int | pa_proplist_contains (const pa_proplist *p, const char *key)
| Returns 1 if an entry for the specified key exists in the property list. More...
void | pa_proplist_clear (pa_proplist *p)
| Remove all entries from the property list object. More...
pa_proplist * | pa_proplist_copy (const pa_proplist *p)
| Allocate a new property list and copy over every single entry from the specified list. More...
unsigned | pa_proplist_size (const pa_proplist *p)
| Return the number of entries in the property list. More...
int | pa_proplist_isempty (const pa_proplist *p)
| Returns 0 when the proplist is empty, positive otherwise. More...
int | pa_proplist_equal (const pa_proplist *a, const pa_proplist *b)
| Return non-zero when a and b have the same keys and values. More...

## Detailed Description

Property list constants and functions.

## Macro Definition Documentation

## ◆ PA_PROP_APPLICATION_ICON_NAME

#define PA_PROP_APPLICATION_ICON_NAME "application.icon_name"

For clients/streams: an XDG icon name for the application.

E.g. "totem"

## ◆ PA_PROP_APPLICATION_ID

#define PA_PROP_APPLICATION_ID "application.id"

For clients/streams: a textual id for identifying an application logically.

E.g. "org.gnome.Totem"

## ◆ PA_PROP_APPLICATION_LANGUAGE

#define PA_PROP_APPLICATION_LANGUAGE "application.language"

For clients/streams: application language if applicable, in standard POSIX format.

E.g. "de_DE"

## ◆ PA_PROP_APPLICATION_NAME

#define PA_PROP_APPLICATION_NAME "application.name"

For clients/streams: localized human readable application name.

E.g. "Totem Music Player"

## ◆ PA_PROP_APPLICATION_PROCESS_BINARY

#define PA_PROP_APPLICATION_PROCESS_BINARY "application.process.binary"

For clients/streams: application process name.

E.g. "totem"

## ◆ PA_PROP_APPLICATION_PROCESS_HOST

#define PA_PROP_APPLICATION_PROCESS_HOST "application.process.host"

For clients/streams: host name the application runs on.

E.g. "omega"

## ◆ PA_PROP_APPLICATION_PROCESS_ID

#define PA_PROP_APPLICATION_PROCESS_ID "application.process.id"

For clients/streams on UNIX: application process PID, an integer formatted as string.

E.g. "4711"

## ◆ PA_PROP_APPLICATION_PROCESS_MACHINE_ID

#define PA_PROP_APPLICATION_PROCESS_MACHINE_ID "application.process.machine_id"

For clients/streams: the D-Bus host id the application runs on.

E.g. "543679e7b01393ed3e3e650047d78f6e"

## ◆ PA_PROP_APPLICATION_PROCESS_SESSION_ID

#define PA_PROP_APPLICATION_PROCESS_SESSION_ID "application.process.session_id"

For clients/streams: an id for the login session the application runs in.

On Unix the value of $XDG_SESSION_ID. E.g. "5"

## ◆ PA_PROP_APPLICATION_PROCESS_USER

#define PA_PROP_APPLICATION_PROCESS_USER "application.process.user"

For clients/streams: application user name.

E.g. "lennart"

## ◆ PA_PROP_APPLICATION_VERSION

#define PA_PROP_APPLICATION_VERSION "application.version"

For clients/streams: a version string, e.g. "0.6.88".

## ◆ PA_PROP_BLUETOOTH_CODEC

#define PA_PROP_BLUETOOTH_CODEC "bluetooth.codec"

For a bluez device: the currently selected codec name.

Since
  15.0

## ◆ PA_PROP_CONTEXT_FORCE_DISABLE_SHM

#define PA_PROP_CONTEXT_FORCE_DISABLE_SHM "context.force.disable.shm"

For context: whether to forcefully disable data transfer via POSIX or memfd shared memory.

This property overrides any other client configuration which would otherwise enable SHM communication channels.

Since
  15.0

## ◆ PA_PROP_DEVICE_ACCESS_MODE

#define PA_PROP_DEVICE_ACCESS_MODE "device.access_mode"

For devices: access mode of the device if applicable.

One of "mmap", "mmap_rewrite", "serial"

## ◆ PA_PROP_DEVICE_API

#define PA_PROP_DEVICE_API "device.api"

For devices: API this device is access with.

E.g. "alsa"

## ◆ PA_PROP_DEVICE_BUFFERING_BUFFER_SIZE

#define PA_PROP_DEVICE_BUFFERING_BUFFER_SIZE "device.buffering.buffer_size"

For devices: buffer size in bytes, integer formatted as string.

## ◆ PA_PROP_DEVICE_BUFFERING_FRAGMENT_SIZE

#define PA_PROP_DEVICE_BUFFERING_FRAGMENT_SIZE "device.buffering.fragment_size"

For devices: fragment size in bytes, integer formatted as string.

## ◆ PA_PROP_DEVICE_BUS

#define PA_PROP_DEVICE_BUS "device.bus"

For devices: bus of the device if applicable.

One of "isa", "pci", "usb", "firewire", "bluetooth"

## ◆ PA_PROP_DEVICE_BUS_PATH

#define PA_PROP_DEVICE_BUS_PATH "device.bus_path"

For devices: bus path to the device in the OS' format.

E.g. "/sys/bus/pci/devices/0000:00:1f.2"

## ◆ PA_PROP_DEVICE_CLASS

#define PA_PROP_DEVICE_CLASS "device.class"

For devices: device class.

One of "sound", "modem", "monitor", "filter"

## ◆ PA_PROP_DEVICE_DESCRIPTION

#define PA_PROP_DEVICE_DESCRIPTION "device.description"

For devices: localized human readable device one-line description.

E.g. "Foobar Industries USB Headset 2000+ Ultra"

## ◆ PA_PROP_DEVICE_FORM_FACTOR

#define PA_PROP_DEVICE_FORM_FACTOR "device.form_factor"

For devices: form factor if applicable.

One of "internal", "speaker", "handset", "tv", "webcam", "microphone", "headset", "headphone", "hands-free", "car", "hifi", "computer", "portable"

## ◆ PA_PROP_DEVICE_ICON_NAME

#define PA_PROP_DEVICE_ICON_NAME "device.icon_name"

For devices: an XDG icon name for the device.

E.g. "sound-card-speakers-usb"

## ◆ PA_PROP_DEVICE_INTENDED_ROLES

#define PA_PROP_DEVICE_INTENDED_ROLES "device.intended_roles"

For devices: intended use.

A space separated list of roles (see PA_PROP_MEDIA_ROLE) this device is particularly well suited for, due to latency, quality or form factor.

Since
  0.9.16

## ◆ PA_PROP_DEVICE_MASTER_DEVICE

#define PA_PROP_DEVICE_MASTER_DEVICE "device.master_device"

For filter devices: master device id if applicable.

## ◆ PA_PROP_DEVICE_PRODUCT_ID

#define PA_PROP_DEVICE_PRODUCT_ID "device.product.id"

For devices: product ID if applicable.

E.g. 4565

## ◆ PA_PROP_DEVICE_PRODUCT_NAME

#define PA_PROP_DEVICE_PRODUCT_NAME "device.product.name"

For devices: product name if applicable.

E.g. "SuperSpeakers 2000 Pro"

## ◆ PA_PROP_DEVICE_PROFILE_DESCRIPTION

#define PA_PROP_DEVICE_PROFILE_DESCRIPTION "device.profile.description"

For devices: human readable one-line description of the profile this device is in.

E.g. "Analog Stereo", ...

## ◆ PA_PROP_DEVICE_PROFILE_NAME

#define PA_PROP_DEVICE_PROFILE_NAME "device.profile.name"

For devices: profile identifier for the profile this devices is in.

E.g. "analog-stereo", "analog-surround-40", "iec958-stereo", ...

## ◆ PA_PROP_DEVICE_SERIAL

#define PA_PROP_DEVICE_SERIAL "device.serial"

For devices: serial number if applicable.

E.g. "4711-0815-1234"

## ◆ PA_PROP_DEVICE_STRING

#define PA_PROP_DEVICE_STRING "device.string"

For devices: device string in the underlying audio layer's format.

E.g. "surround51:0"

## ◆ PA_PROP_DEVICE_VENDOR_ID

#define PA_PROP_DEVICE_VENDOR_ID "device.vendor.id"

For devices: vendor ID if applicable.

E.g. 1274

## ◆ PA_PROP_DEVICE_VENDOR_NAME

#define PA_PROP_DEVICE_VENDOR_NAME "device.vendor.name"

For devices: vendor name if applicable.

E.g. "Foocorp Heavy Industries"

## ◆ PA_PROP_EVENT_DESCRIPTION

#define PA_PROP_EVENT_DESCRIPTION "event.description"

For event sound streams: localized human readable one-line description of the event, formatted as UTF-8.

E.g. "Email from lennart@example.com received."

## ◆ PA_PROP_EVENT_ID

#define PA_PROP_EVENT_ID "event.id"

For event sound streams: XDG event sound name.

e.g. "message-new-email" (Event sound streams are those with media.role set to "event")

## ◆ PA_PROP_EVENT_MOUSE_BUTTON

#define PA_PROP_EVENT_MOUSE_BUTTON "event.mouse.button"

For event sound streams: mouse button that triggered the event if applicable, integer formatted as string with 0=left, 1=middle, 2=right.

E.g. "0"

## ◆ PA_PROP_EVENT_MOUSE_HPOS

#define PA_PROP_EVENT_MOUSE_HPOS "event.mouse.hpos"

For event sound streams: relative horizontal mouse position on the screen if the event sound was triggered by a mouse click, float formatted as text string, ranging from 0.0 (left side of the screen) to 1.0 (right side of the screen).

E.g. "0.65"

## ◆ PA_PROP_EVENT_MOUSE_VPOS

#define PA_PROP_EVENT_MOUSE_VPOS "event.mouse.vpos"

For event sound streams: relative vertical mouse position on the screen if the event sound was triggered by a mouse click, float formatted as text string, ranging from 0.0 (top of the screen) to 1.0 (bottom of the screen).

E.g. "0.43"

## ◆ PA_PROP_EVENT_MOUSE_X

#define PA_PROP_EVENT_MOUSE_X "event.mouse.x"

For event sound streams: absolute horizontal mouse position on the screen if the event sound was triggered by a mouse click, integer formatted as text string.

E.g. "865"

## ◆ PA_PROP_EVENT_MOUSE_Y

#define PA_PROP_EVENT_MOUSE_Y "event.mouse.y"

For event sound streams: absolute vertical mouse position on the screen if the event sound was triggered by a mouse click, integer formatted as text string.

E.g. "432"

## ◆ PA_PROP_FILTER_APPLY

#define PA_PROP_FILTER_APPLY "filter.apply"

For streams: the name of a filter that is desired, e.g. "echo-cancel" or "equalizer-sink".

Differs from PA_PROP_FILTER_WANT in that it forces PulseAudio to apply the filter, regardless of whether PulseAudio thinks it makes sense to do so or not. If this is set, PA_PROP_FILTER_WANT is ignored. In other words, you almost certainly do not want to use this.

Since
  1.0

## ◆ PA_PROP_FILTER_SUPPRESS

#define PA_PROP_FILTER_SUPPRESS "filter.suppress"

For streams: the name of a filter that should specifically suppressed (i.e. overrides PA_PROP_FILTER_WANT).

Useful for the times that PA_PROP_FILTER_WANT is automatically added (e.g. echo-cancellation for phone streams when $VOIP_APP does its own, internal AEC)

Since
  1.0

## ◆ PA_PROP_FILTER_WANT

#define PA_PROP_FILTER_WANT "filter.want"

For streams: the name of a filter that is desired, e.g. "echo-cancel" or "equalizer-sink".

PulseAudio may choose to not apply the filter if it does not make sense (for example, applying echo-cancellation on a Bluetooth headset probably does not make sense.

Since
  1.0

## ◆ PA_PROP_FORMAT_CHANNEL_MAP

#define PA_PROP_FORMAT_CHANNEL_MAP "format.channel_map"

For PCM formats: the channel map of the stream as returned by pa_channel_map_snprint()

Since
  1.0

## ◆ PA_PROP_FORMAT_CHANNELS

#define PA_PROP_FORMAT_CHANNELS "format.channels"

For all formats: the number of channels (unsigned integer)

Since
  1.0

## ◆ PA_PROP_FORMAT_RATE

#define PA_PROP_FORMAT_RATE "format.rate"

For all formats: the sample rate (unsigned integer)

Since
  1.0

## ◆ PA_PROP_FORMAT_SAMPLE_FORMAT

#define PA_PROP_FORMAT_SAMPLE_FORMAT "format.sample_format"

For PCM formats: the sample format used as returned by pa_sample_format_to_string()

Since
  1.0

## ◆ PA_PROP_MEDIA_ARTIST

#define PA_PROP_MEDIA_ARTIST "media.artist"

For streams: localized media artist if applicable, formatted as UTF-8.

E.g. "Guns'N'Roses"

## ◆ PA_PROP_MEDIA_COPYRIGHT

#define PA_PROP_MEDIA_COPYRIGHT "media.copyright"

For streams: localized media copyright string if applicable, formatted as UTF-8.

E.g. "Evil Record Corp."

## ◆ PA_PROP_MEDIA_FILENAME

#define PA_PROP_MEDIA_FILENAME "media.filename"

For streams: source filename if applicable, in URI format or local path.

E.g. "/home/lennart/music/foobar.ogg"

## ◆ PA_PROP_MEDIA_ICON_NAME

#define PA_PROP_MEDIA_ICON_NAME "media.icon_name"

For streams: an XDG icon name for the media.

E.g. "audio-x-mp3"

## ◆ PA_PROP_MEDIA_LANGUAGE

#define PA_PROP_MEDIA_LANGUAGE "media.language"

For streams: media language if applicable, in standard POSIX format.

E.g. "de_DE"

## ◆ PA_PROP_MEDIA_NAME

#define PA_PROP_MEDIA_NAME "media.name"

For streams: localized media name, formatted as UTF-8.

E.g. "Guns'N'Roses: Civil War".

## ◆ PA_PROP_MEDIA_ROLE

#define PA_PROP_MEDIA_ROLE "media.role"

For streams: logic role of this media.

One of the strings "video", "music", "game", "event", "phone", "animation", "production", "a11y", "test"

## ◆ PA_PROP_MEDIA_SOFTWARE

#define PA_PROP_MEDIA_SOFTWARE "media.software"

For streams: localized media generator software string if applicable, formatted as UTF-8.

E.g. "Foocrop AudioFrobnicator"

## ◆ PA_PROP_MEDIA_TITLE

#define PA_PROP_MEDIA_TITLE "media.title"

For streams: localized media title if applicable, formatted as UTF-8.

E.g. "Civil War"

## ◆ PA_PROP_MODULE_AUTHOR

#define PA_PROP_MODULE_AUTHOR "module.author"

For modules: the author's name, formatted as UTF-8 string.

E.g. "Lennart Poettering"

## ◆ PA_PROP_MODULE_DESCRIPTION

#define PA_PROP_MODULE_DESCRIPTION "module.description"

For modules: a human readable one-line description of the module's purpose formatted as UTF-8.

E.g. "Frobnicate sounds with a flux compensator"

## ◆ PA_PROP_MODULE_USAGE

#define PA_PROP_MODULE_USAGE "module.usage"

For modules: a human readable usage description of the module's arguments formatted as UTF-8.

## ◆ PA_PROP_MODULE_VERSION

#define PA_PROP_MODULE_VERSION "module.version"

For modules: a version string for the module.

E.g. "0.9.15"

## ◆ PA_PROP_WINDOW_DESKTOP

#define PA_PROP_WINDOW_DESKTOP "window.desktop"

For streams that belong to a window on the screen: if the windowing system supports multiple desktops, a comma separated list of indexes of the desktops this window is visible on.

If this property is an empty string, it is visible on all desktops (i.e. 'sticky'). The first desktop is 0. E.g. "0,2,3"

Since
  0.9.18

## ◆ PA_PROP_WINDOW_HEIGHT

#define PA_PROP_WINDOW_HEIGHT "window.height"

For streams that belong to a window on the screen: window height on the screen, integer formatted as text string.

E.g. "643".

Since
  0.9.17

## ◆ PA_PROP_WINDOW_HPOS

#define PA_PROP_WINDOW_HPOS "window.hpos"

For streams that belong to a window on the screen: relative position of the window center on the screen, float formatted as text string, ranging from 0.0 (left side of the screen) to 1.0 (right side of the screen).

E.g. "0.65".

Since
  0.9.17

## ◆ PA_PROP_WINDOW_ICON_NAME

#define PA_PROP_WINDOW_ICON_NAME "window.icon_name"

For streams that belong to a window on the screen: an XDG icon name for the window.

E.g. "totem"

## ◆ PA_PROP_WINDOW_ID

#define PA_PROP_WINDOW_ID "window.id"

For streams that belong to a window on the screen: a textual id for identifying a window logically.

E.g. "org.gnome.Totem.MainWindow"

## ◆ PA_PROP_WINDOW_NAME

#define PA_PROP_WINDOW_NAME "window.name"

For streams that belong to a window on the screen: localized window title.

E.g. "Totem Music Player"

## ◆ PA_PROP_WINDOW_VPOS

#define PA_PROP_WINDOW_VPOS "window.vpos"

For streams that belong to a window on the screen: relative position of the window center on the screen, float formatted as text string, ranging from 0.0 (top of the screen) to 1.0 (bottom of the screen).

E.g. "0.43".

Since
  0.9.17

## ◆ PA_PROP_WINDOW_WIDTH

#define PA_PROP_WINDOW_WIDTH "window.width"

For streams that belong to a window on the screen: window width on the screen, integer formatted as text string.

e.g. "365".

Since
  0.9.17

## ◆ PA_PROP_WINDOW_X

#define PA_PROP_WINDOW_X "window.x"

For streams that belong to a window on the screen: absolute horizontal window position on the screen, integer formatted as text string.

E.g. "865".

Since
  0.9.17

## ◆ PA_PROP_WINDOW_X11_DISPLAY

#define PA_PROP_WINDOW_X11_DISPLAY "window.x11.display"

For streams that belong to an X11 window on the screen: the X11 display string.

E.g. ":0.0"

## ◆ PA_PROP_WINDOW_X11_MONITOR

#define PA_PROP_WINDOW_X11_MONITOR "window.x11.monitor"

For streams that belong to an X11 window on the screen: the X11 monitor the window is on, an integer formatted as string.

E.g. "0"

## ◆ PA_PROP_WINDOW_X11_SCREEN

#define PA_PROP_WINDOW_X11_SCREEN "window.x11.screen"

For streams that belong to an X11 window on the screen: the X11 screen the window is on, an integer formatted as string.

E.g. "0"

## ◆ PA_PROP_WINDOW_X11_XID

#define PA_PROP_WINDOW_X11_XID "window.x11.xid"

For streams that belong to an X11 window on the screen: the window XID, an integer formatted as string.

E.g. "25632"

## ◆ PA_PROP_WINDOW_Y

#define PA_PROP_WINDOW_Y "window.y"

For streams that belong to a window on the screen: absolute vertical window position on the screen, integer formatted as text string.

E.g. "343".

Since
  0.9.17

## Typedef Documentation

## ◆ pa_proplist

typedef struct pa_proplist pa_proplist

A property list object.

Basically a dictionary with ASCII strings as keys and arbitrary data as values.

Since
  0.9.11

## ◆ pa_update_mode_t

typedef enum pa_update_mode pa_update_mode_t

Update mode enum for pa_proplist_update().

Since
  0.9.11

## Enumeration Type Documentation

## ◆ pa_update_mode

enum pa_update_mode

Update mode enum for pa_proplist_update().

Since
  0.9.11

Enumerator
PA_UPDATE_SET | Replace the entire property list with the new one. Don't keep any of the old data around.
PA_UPDATE_MERGE | Merge new property list into the existing one, not replacing any old entries if they share a common key with the new property list.
PA_UPDATE_REPLACE | Merge new property list into the existing one, replacing all old entries that share a common key with the new property list.

## Function Documentation

## ◆ pa_proplist_clear()

void pa_proplist_clear | ( | pa_proplist * | p | ) |

Remove all entries from the property list object.

Since
  0.9.11

## ◆ pa_proplist_contains()

int pa_proplist_contains | ( | const pa_proplist * | p,
|  | const char * | key
| ) |  |

Returns 1 if an entry for the specified key exists in the property list.

Returns negative on error.

Since
  0.9.11

## ◆ pa_proplist_copy()

pa_proplist * pa_proplist_copy | ( | const pa_proplist * | p | ) |

Allocate a new property list and copy over every single entry from the specified list.

Since
  0.9.11

## ◆ pa_proplist_equal()

int pa_proplist_equal | ( | const pa_proplist * | a,
|  | const pa_proplist * | b
| ) |  |

Return non-zero when a and b have the same keys and values.

Since
  0.9.16

## ◆ pa_proplist_free()

void pa_proplist_free | ( | pa_proplist * | p | ) |

Free the property list.

Since
  0.9.11

## ◆ pa_proplist_from_string()

pa_proplist * pa_proplist_from_string | ( | const char * | str | ) |

Allocate a new property list and assign key/value from a human readable string.

Since
  0.9.15

## ◆ pa_proplist_get()

int pa_proplist_get | ( | const pa_proplist * | p,
|  | const char * | key,
|  | const void ** | data,
|  | size_t * | nbytes
| ) |  |

Store the value for the specified key in data.

Will store a NUL-terminated string for string entries. The data pointer returned will point to an internally allocated buffer. The caller should make a copy of the data before any subsequent modification or destruction of the property list. Returns zero on success, negative on error.

Since
  0.9.11

## ◆ pa_proplist_gets()

const char * pa_proplist_gets | ( | const pa_proplist * | p,
|  | const char * | key
| ) |  |

Return a string entry for the specified key.

Will return NULL if the data is not valid UTF-8. Will return a NUL-terminated string in an internally allocated buffer. The caller should make a copy of the data before accessing the property list again.

Since
  0.9.11

## ◆ pa_proplist_isempty()

int pa_proplist_isempty | ( | const pa_proplist * | p | ) |

Returns 0 when the proplist is empty, positive otherwise.

Since
  0.9.15

## ◆ pa_proplist_iterate()

const char * pa_proplist_iterate | ( | const pa_proplist * | p,
|  | void ** | state
| ) |  |

Iterate through the property list.

The user should allocate a state variable of type void* and initialize it with NULL. A pointer to this variable should then be passed to pa_proplist_iterate() which should be called in a loop until it returns NULL which signifies EOL. The property list should not be modified during iteration through the list – with the exception of deleting the current entry. On each invocation this function will return the key string for the next entry. The keys in the property list do not have any particular order.

Since
  0.9.11

## ◆ pa_proplist_key_valid()

int pa_proplist_key_valid | ( | const char * | key | ) |

Returns a non-zero value if the key is valid.

Since
  3.0

## ◆ pa_proplist_new()

pa_proplist * pa_proplist_new | ( | void |  | ) |

Allocate a property list.

Free with pa_proplist_free.

Since
  0.9.11

## ◆ pa_proplist_set()

int int pa_proplist_set | ( | pa_proplist * | p,
|  | const char * | key,
|  | const void * | data,
|  | size_t | nbytes
| ) |  |

Append a new arbitrary data entry to the property list, possibly overwriting an already existing entry with the same key.

An internal copy of the data passed is made. Returns zero on success.

Since
  0.9.11

## ◆ pa_proplist_setf()

int pa_proplist_setf | ( | pa_proplist * | p,
|  | const char * | key,
|  | const char * | format,
|  |  | ...
| ) |  |

Append a new string entry to the property list, possibly overwriting an already existing entry with the same key.

An internal copy of the data passed is made. Will accept only valid UTF-8. The data can be passed as printf()-style format string with arguments. Returns zero on success.

Since
  0.9.11

## ◆ pa_proplist_setp()

int pa_proplist_setp | ( | pa_proplist * | p,
|  | const char * | pair
| ) |  |

Append a new string entry to the property list, possibly overwriting an already existing entry with the same key.

An internal copy of the data passed is made. Will accept only valid UTF-8. The string passed in must contain a '='. Left hand side of the '=' is used as key name, the right hand side as string data. Returns zero on success.

Since
  0.9.16

## ◆ pa_proplist_sets()

int pa_proplist_sets | ( | pa_proplist * | p,
|  | const char * | key,
|  | const char * | value
| ) |  |

Append a new string entry to the property list, possibly overwriting an already existing entry with the same key.

An internal copy of the data passed is made. Will accept only valid UTF-8. Returns zero on success.

Since
  0.9.11

## ◆ pa_proplist_size()

unsigned pa_proplist_size | ( | const pa_proplist * | p | ) |

Return the number of entries in the property list.

Since
  0.9.15

## ◆ pa_proplist_to_string()

char * pa_proplist_to_string | ( | const pa_proplist * | p | ) |

Format the property list nicely as a human readable string.

This works very much like pa_proplist_to_string_sep() and uses a newline as separator and appends one final one. Call pa_xfree() on the result.

Since
  0.9.11

## ◆ pa_proplist_to_string_sep()

char * pa_proplist_to_string_sep | ( | const pa_proplist * | p,
|  | const char * | sep
| ) |  |

Format the property list nicely as a human readable string and choose the separator.

Call pa_xfree() on the result.

Since
  0.9.15

## ◆ pa_proplist_unset()

int pa_proplist_unset | ( | pa_proplist * | p,
|  | const char * | key
| ) |  |

Removes a single entry from the property list, identified be the specified key name.

Returns zero on success, negative on error.

Since
  0.9.11

## ◆ pa_proplist_unset_many()

int pa_proplist_unset_many | ( | pa_proplist * | p,
|  | const char *const | keys[]
| ) |  |

Similar to pa_proplist_unset() but takes an array of keys to remove.

The array should be terminated by a NULL pointer. Returns -1 on failure, otherwise the number of entries actually removed (which might even be 0, if there were no matching entries to remove).

Since
  0.9.11

## ◆ pa_proplist_update()

void pa_proplist_update | ( | pa_proplist * | p,
|  | pa_update_mode_t | mode,
|  | const pa_proplist * | other
| ) |  |

Merge property list "other" into "p", adhering the merge mode as specified in "mode".

Since
  0.9.11