Modules [Link]

org/wiki/Software/PulseAudio/Documentation/User/Modules/

www/ Software/ PulseAudio/ Documentation/ User/ Modules Edit Page History Repo Info

Home • About • Community • Download • Documentation • Planet

I. Loadable Modules
1. Device Drivers
a. module-pipe-sink
b. module-pipe-source
c. module-null-sink
d. module-alsa-sink
e. module-alsa-source
f. module-alsa-card
g. module-oss
h. module-solaris
i. module-waveout
j. module-combine
k. module-combine-sink
l. module-remap-sink
m. module-remap-source
n. module-tunnel-{sink,source}
o. module-tunnel-sink-new
p. module-tunnel-source-new
q. module-esound-sink
2. Protocols
a. module-cli
b. module-cli-protocol-{unix,tcp}
c. module-simple-protocol-{unix,tcp}
d. module-esound-protocol-{unix,tcp}
e. module-native-protocol-{unix,tcp}
f. module-native-protocol-fd
g. module-http-protocol-tcp
3. Saving/restoring settings
a. module-default-device-restore
b. module-card-restore
c. module-device-restore
d. module-stream-restore
e. module-device-manager
4. X Window System
a. module-x11-bell
b. module-x11-publish
c. module-x11-xsmp

1 of 24 08/07/2017 12:26 PM
Modules [Link]

5. Volume Control
a. module-mmkbd-evdev
b. module-lirc
6. Bluetooth
a. module-bluetooth-discover
b. module-bluetooth-policy
c. module-bluetooth-proximity
7. RTP/SDP/SAP Transport
a. module-rtp-send
b. module-rtp-recv
8. RAOP Sink (Wireless Network Sound aka Apple Airtunes)
a. module-raop-discover
b. module-raop-sink
9. JACK Connectivity
a. module-jack-sink
b. module-jack-source
c. module-jackdbus-detect
10. Filters
a. module-echo-cancel
b. module-equalizer-sink
c. module-ladspa-sink
d. module-virtual-surround-sink
11. Miscellaneous
a. module-sine
b. module-sine-source
c. module-esound-compat-spawnfd
d. module-esound-compat-spawnpid
e. module-match
f. module-udev-detect
g. module-detect
h. module-zeroconf-publish
i. module-zeroconf-discover
j. module-rescue-streams
k. module-systemd-login
l. module-console-kit
m. module-position-event-sounds
n. module-always-sink
o. module-suspend-on-idle
p. module-loopback
q. module-switch-on-connect
r. module-role-ducking
s. module-allow-passthrough

Loadable Modules
To show all currently loaded modules with their arguments, run pacmd and enter the CLI command list-modules . The following loadable modules are provided with the
PulseAudio distribution:

Device Drivers
All device driver modules support the following parameters:

2 of 24 08/07/2017 12:26 PM
Modules [Link]

sink_name, source_name
Name for the sink (resp. source). Allowed characters in the name are a-z, A-Z, numbers, period (.) and underscore (_). The length must be 1-128 characters.
format
The sample format (one of u8, s16, s16be, s16le, float32, float32be, float32le, alaw, ulaw) (defaults to s16)
rate
The sample rate (defaults to 44100)
channels
Audio channels (defaults to 2)
channel_map
Channel map. A list of comma-separated channel names. The currently defined channel names are: left, right, mono, center, front-left, front-right, front-center,
rear-center, rear-left, rear-right, lfe, subwoofer, front-left-of-center, front-right-of-center, side-left, side-right, aux0, aux1 to aux15, top-center, top-front-left,
top-front-right, top-front-center, top-rear-left, top-rear-right, top-rear-center, (Default depends on the number of channels and the driver)

Since 0.9.8

format
The sample format can be signed 32 bit (s32, s32le, s32be)

Since 0.9.15

format
The sample format can be signed 24 bit, packed in 3 or 4 bytes (s24, s24le, s24be, s24-32, s24-32le, s24-32be)

Since 0.9.16

sink_properties, source_properties

Set additional properties of the sink/source. For example, you can set the description directly when the module is loaded by setting this parameter.

load-module module-alsa-sink sink_name=headphones sink_properties=[Link]=Headphones

This is the same as using the update-sink-proplist command after the sink is setup, either with pacmd or in [Link].

update-sink-proplist SINKNAME [Link]="DESCRIPTION"

module-pipe-sink

Provides a simple test sink that writes the audio data to a FIFO special file in the file system. The sink name defaults to fifo_output.

The following option is supported:

file
The name of the FIFO special file to use. (defaults to: /tmp/[Link])

module-pipe-source

Provides a simple test source that reads the audio data from a FIFO special file in the file system. The source name defaults to fifo_input.

The following option is supported:

file
The name of the FIFO special file to use. (defaults to: /tmp/[Link])

3 of 24 08/07/2017 12:26 PM
Modules [Link]

module-null-sink

Provides a simple null sink. All data written to this sink is silently dropped. This sink is clocked using the system time.

This module doesn't support any special parameters

module-alsa-sink

Provides a playback sink for devices supported by the Advanced Linux Sound Architecture (ALSA). The sink name defaults to alsa_output.

You should (almost) never need to load this module manually. Let module-udev-detect look for the supported cards and then select the profile you want, that will make
the right sinks show up.

In addition to the general device driver options described above this module supports:

device
The ALSA device to use. (defaults to "default")
fragments
The desired fragments when opening the device. (defaults to 12)
fragment_size
The desired fragment size in bytes when opening the device (defaults to 1024)
tsched
Since 0.9.11. Use system-timer based model (aka glitch-free). Defaults to 1 (enabled). If your hardware does not return accurate timing information (e.g.
Creative sound cards) you can try to set tsched=0 to enable the interupt based timing which was used in 0.9.10 and before.
mmap name
String to prefix to the automatically determined sink name.
device_id tsched_buffer_size, tsched_watermark ignore_dB
Ignore dB information from the device
control
Name of mixer control
namereg_fail
Boolean
deferred_volume
Syncronize sw and hw volume changes in IO-thread
fixed_latency_range
Since 2.0. Boolean. Normally when there's an alsa underrun, and timer based scheduling is used, the alsa sink will raise the minimum latency that
applications can get to avoid further underruns. If this option is enabled, the minimum latency will stay constant even if underruns occur.

module-alsa-source

Provides a recording source for devices supported by the Advanced Linux Sound Architecture (ALSA). The source name defaults to alsa_input.

You should (almost) never need to load this module manually. Let module-udev-detect look for the supported cards and then select the profile you want, that will make
the right sources show up.

This module supports device=, fragments=, fragment_size= and tsched= arguments the same way as module-alsa-sink. Also mmap, name, device, control,
tsched_buffer_size, tsched_watermark, ignore_dB, namereg_fail, fixed_latency_range

module-alsa-card

Creates a PulseAudio card for an ALSA card. The "device_id" argument is mandatory, it tells PulseAudio which ALSA card to use.

card_name

4 of 24 08/07/2017 12:26 PM
Modules [Link]

Name for the PulseAudio card.

card_properties
Extra properties to be stored in the card's property list.
sink_name
Name to be used by the card's sinks. If the card has any profiles that have multiple sinks, then this argument can't be used, because the sink names can't all
be the same.
sink_properties
Extra properties to be stored in the property lists of the card's sinks.
source_name
Name to be used by the card's sources. If the card has any profiles that have multiple sources, then this argument can't be used, because the source names
can't all be the same.
namereg_fail
A boolean. If "true", loading the card will fail if there already exists a card with the same name. If "false", a suffix is added to the card name if there already
exists a card with the same name.
profile
The initial profile to activate when loading the module.
profile_set
Profile set configuration file. Can be an absolute path, or relative to the standard profile-sets directory.
device_id
The alsa card identifier. Can be the card index or the name. See /proc/asound/cards for the list of available cards and their identifiers.
format
The sample format to be used by the card's sinks and sources.
rate
The sample rate to be used by the card's sinks and sources.
name
The "device_id" argument is used by default as a part of the card name (if "card_name" is not given), and also in the card's sink and source names. If you're not
happy with that for some reason, this argument can be given to be a substitute for "device_id" in the card, sink and source names.
tsched
A boolean. If "true", the sinks and sources of this card will use the timer-based scheduling.
ignore_dB
A boolean. If "true", any decibel information given by the ALSA drivers will be ignored (useful if that information is wrong).
fragments
The number of fragments to be used in the sink and source buffers. Only effective if the timer-based scheduling is disabled.
fragment_size
The size of one fragment (in bytes) to be used in the sink and source buffers. Only effective if the timer-based scheduling is disabled.
mmap
A boolean. If "true", PulseAudio will access ALSA using the mmap interface.
tsched_buffer_size
The total sink and source buffer size in bytes. Only effective if the timer-based scheduling is enabled.
tsched_buffer_watermark
The buffer fill level (in bytes) at which the sinks must refill the buffer. Only effective if the timer-based scheduling is enabled.
deferred_volume
A boolean. If "true", PulseAudio will slightly delay hardware volume changes in order to synchronize the changes with software volume changes.
fixed_latency_range
A boolean. Normally when there's an alsa underrun or overrun, and timer-based scheduling is used, the alsa sink or source will raise the minimum latency that
applications can get to avoid further underruns or overruns. If this option is enabled, the minimum latency will stay constant even if underruns or overruns
occur.
use_ucm
A boolean. If "true", the card will use the ALSA Use Case Manager interface for configuration, if it's available. If "false", or if there's no UCM configuration for
the card, PulseAudio's own profile and path configuration files will be used instead.

module-oss

5 of 24 08/07/2017 12:26 PM
Modules [Link]

Provides both a sink and a source for playback, resp. recording on Open Sound System (OSS) compatible devices. This module supports the following options:

record, playback
Accepts a boolean value for enabling the playback, resp. recording on this device. (defaults: to 1)
device
The OSS device to use. (defaults to /dev/dsp),
mmap
Accepts a boolean value for enabling (resp. disabling) memory mapped (mmap()) access to the input/output buffers of the audio device. This provides better
latency behaviour but is less compatible. (defaults: to 1).
fragments, fragment_size
As in module-alsa-sink.

The sink name (resp. source name) defaults to oss_output (resp. oss_input).

module-solaris

Provides a sink and source for the Solaris audio device.

In addition to the general device driver options described above this module supports:

record, playback
Accepts a boolean value for enabling the playback, resp. recording on this device. (defaults: to 1)
device
Audio device filename
buffer_length
Record buffer length in ms.

module-waveout

Provides both a sink and source for the Win32 audio device. This module supports the following options:

record, playback
Accepts a boolean value for enabling the playback, resp. recording on this device. (defaults: to 1)
device
Accepts an integer specifying the Windows audio device to be opened. If not set the ?WaveMapper service is used.
fragments, fragment_size
As in module-alsa-sink.

The sink name (resp. source name) defaults to wave_output (resp. wave_input).

module-combine

Renamed to module-combine-sink in 1.0. See module-combine-sink for the documentation for this module.

module-combine-sink

Since 1.0 (prior to 1.0 this same module was available with name "module-combine"). This combines two or more sinks into one. A new virtual sink is allocated.
All data written to it is forwarded to all connected sinks. In equidistant intervals the sample rates of the output sinks is recalculated: i.e. even when the sinks' crystals
deviate (which is normally the case) output appears synchronously to the human ear. The resampling required for this may be very CPU intensive.

sink_name
The name for the combined sink. (defaults to "combined")
sink_properties

6 of 24 08/07/2017 12:26 PM
Modules [Link]

Since 0.9.15. Property list for the combined sink.

slaves
Name of sinks to link into the combined think, separated by commas.
adjust_time
Time in seconds when to readjust the sample rate of all sinks. Zero means that readjustment should be disabled. Default: 10.
resample_method
Resampling algorithm to use when adjusting to the sample rate differences between the slave sinks. TODO: Create a page, and add a link to it here, that
explains all the different resamplers that are available. While waiting for that to happen, users can refer to man [Link], more specifically the resample-
method option documentation.
format, rate, channels, channel_map
Parameters for the combined sink. See the Device Drivers section at the top of this page for details.

module-remap-sink

Since 0.9.7. The module creates a new virtual sink, which connects to a master sink using a virtual stream. The virtual stream's channel map is configurable, which
makes it possible to control which channels of the master sink will be used. The channel map of the virtual sink itself can be configured too. This allows, for example,
creating a virtual stereo sink that only plays to the rear channels of a surround master sink.

Whenever a stream has different channels than the sink it connects to, pulseaudio may apply a remixing algorithm. This remixing is also applied to the virtual stream
created by module-remap-sink, unless the "remix" argument is set to "no". This is a stupid default, because usually you only want to play to the master sink channels
that you configured with the "master_channel_map" argument, so remember to pass "remix=no" when loading module-remap-sink.

sink_name
The name for the new virtual sink.
master
The name of the sink of which channels you're remapping.
channels
Channel count of the new sink.
channel_map
List of the channels that this sink will accept.
master_channel_map
The channels in the master sink, where the channels listed in channel_map will be relayed to. channel_map and master_channel_map must have equal number
of channels listed, because the channels will be mapped based on their position in the list, i.e. the first channel in channel_map will be relayed to the first
channel in master_channel_map and so on.
remix
Allow remixing of the virtual stream. The default is "yes" for some strange reason, but probably you want to set this to "no".

Here's an example for creating a virtual stereo sink that will play to the rear channels of the master sink. Replace MASTER_SINK_NAME with the real name of the
master sink.

load-module module-remap-sink sink_name=rear_stereo master=MASTER_SINK_NAME channels=2 master_channel_map=rear-left,rear-right channel_map=front-left,front-right remix=no

module-remap-source

Since 4.0. This creates a virtual source ("remapped source") on top of another source ("master source"), with a different channel map.

source_name
Name for the remapped source.
source_properties
Extra properties for the remapped source.
master
Name or index of the master source.

7 of 24 08/07/2017 12:26 PM
Modules [Link]

master_channel_map
The master source's channels from which audio should be captured.
format
The remapped source sample format.
rate
The remapped source sample rate.
channels
The number of channels of the remapped source. This is rarely useful, because the number of channels is already implied by the channel_map and
master_channel_map arguments, and the channels argument can't conflict with those other arguments. If neither channel_map nor master_channel_map is
specified, then this can be used to control the channel count of the remapped source, but in that case the module is pretty useless, because no remapping will
be done.
channel_map
The channel map of the remapped source. This must have the same number of channels as master_channel_map. The remapping happens so that the first
channel in master_channel_map is copied to the first channel in channel_map etc.
remix
A boolean. This can be used for disabling remixing for the stream that is created between the master source and the remapped source. If this is set to "yes",
the remixing behaviour will be the same as all other streams (which depends on configuration elsewhere). Remixing means that if the master source has
channels that are not listed in master_channel_map, those channels may be mixed to the channels that are listed in master_channel_map. Likewise, if
master_channel_map has channels that the master source doesn't actually have, then other channels may be used as a substitute for the missing channels.
This is often undesirable when using module-remap-source, so it's a common thing to disable remixing.

Here's an example for swapping the channels of a stereo source. We assume that the system has a stereo source named "alsa_input.pci-0000_00_1b.[Link]-stereo".

load-module module-remap-source master=alsa_input.pci-0000_00_1b.[Link]-stereo master_channel_map=front-left,front-right channel_map=front-right,front-left

module-tunnel-{sink,source}

Tunnel a remote sink/source to a local "ghost" sink/source. Requires a running PulseAudio daemon on the remote server with module-native-protocol-tcp loaded. See
Network Setup for reasons on whether to use a tunnel or direct connection to the remote server.

server
The server to connect to
source
The source on the remote server. Only available for module-tunnel-source.
sink
The sink on the remote server. Only available for module-tunnel-sink.
cookie
The authentication cookie file to use.
auto
Since 5.0. A boolean. If this is set to true, then the default connection parameters and default remote device are gathered from the environment in the same
way as applications do. This is usually a bad idea: the default server is very likely the same server where the tunnel module is being loaded, so enabling this
option carelessly will probably cause the local server to connect to itself.

module-tunnel-sink-new

Since 5.0

This is a reimplementation of module-tunnel-sink. Once this new version is ready, it will be renamed to module-tunnel-sink and the old implementation will be removed.
Note that if you load the module in some configuration file or script, that will break when the rename will happen.

sink_name
Name for the local sink.

8 of 24 08/07/2017 12:26 PM
Modules [Link]

sink_properties
Additional properties for the local sink.
server
The server to connect to. (mandatory argument)
sink
The remote sink to connect to.
format
The sample format of the local sink (the local format is also what will be used in the stream that is sent over the network).
channels
The number of channels of the local sink (the local channel count is also what will be used in the stream that is sent over the network).
channel_map
The channel map of the local sink.
rate
The sample rate of the local sink (the local sample rate is also what will be used in the stream that is sent over the network).
cookie
The cookie file to be used when authenticating to the remote server.

module-tunnel-source-new

Since 5.0

This is a reimplementation of module-tunnel-source. Once this new version is ready, it will be renamed to module-tunnel-source and the old implementation will be
removed. Note that if you load the module in some configuration file or script, that will break when the rename will happen.

source_name
Name for the local source.
source_properties
Additional properties for the local source.
server
The server to connect to. (mandatory argument)
source
The remote source to connect to.
format
The sample format of the local source (the local format is also what will be used in the stream that is received over the network).
channels
The number of channels of the local source (the local channel count is also what will be used in the stream that is received over the network).
channel_map
The channel map of the local source.
rate
The sample rate of the local source (the local sample rate is also what will be used in the stream that is received over the network).
cookie
The cookie file to be used when authenticating to the remote server.

module-esound-sink

Create a playback sink using an ESOUND server as backend. Whenever you can, try to omit this module since it has many disadvantages including bad latency and even
worse latency measurement.

This module lacks the channel_map argument.

server
The server to connect to

9 of 24 08/07/2017 12:26 PM
Modules [Link]

cookie
The authentication cookie file to use.

Protocols
module-cli

Provides the user with a simple command line interface on the controlling TTY of the daemon. This module may not be loaded more than once.

exit_on_eof
Accepts a binary numerical argument specifying whether the daemon should exit after an EOF was received from STDIN (default: 0)

module-cli-protocol-{unix,tcp}

An implementation of a simple command line based protocol for controlling the PulseAudio daemon. If loaded, the user may connect with tools like netcat, telnet or
bidilink to the listening sockets and execute commands the same way as with module-cli.

Beware: Users are not authenticated when connecting to this service.

This module exists in two versions: with the suffix -unix the service will listen on an UNIX domain socket in the local file system. With the suffix -tcp it will listen on a
network transparent TCP/IP socket. (Both IPv6 and IPv4 - if available)

This module supports the following options:

port (only for -tcp)

The port number to listen on (defaults to 4712)
loopback (only for -tcp)
Removed in 0.9.3: Accepts a numerical binary value. If 1 the socket is bound to the loopback device, i.e. not publicly accessible. (defaults to 1)
listen (only for -tcp)
The IP address to listen on. If specified, supersedes the value specified in loopback=
socket (only for -unix)
The UNIX socket name (defaults to /tmp/pulse/cli)

module-simple-protocol-{unix,tcp}

An implementation of a simple protocol which allows playback by using simple tools like netcat. Just connect to the listening socket of this module and write the audio
data to it, or read it from it for playback, resp. recording.

Beware! Users are not authenticated when connecting to this service.

See module-cli-protocol-{unix,tcp} for more information about the two possible suffixes of this module.

In addition to the options supported by module-cli-protocol-*, this module supports:

rate, format, channels

Sample format for streams connecting to this service.
playback, record
Enable/disable playback/recording
sink, source
Specify the sink/source this service connects to

module-esound-protocol-{unix,tcp}

10 of 24 08/07/2017 12:26 PM
Modules [Link]

An implementation of a protocol compatible with the Enlightened Sound Daemon (ESOUND, esd). When you load this module you may access the PulseAudio daemon
with tools like esdcat, esdrec or even esdctl. Many applications, such as XMMS, include support for this protocol.

See module-cli-protocol-{unix,tcp} for more information about the two possible suffixes of this module.

In addition to the options supported by module-cli-protocol-*, this module supports:

sink, source
Specify the sink/source this service connects to
auth-anonymous
If set to 1 no authentication is required to connect to the service
auth-cookie
New in 0.9.12: Name of the cookie file for authentication purposes. Defaults to ".esd_auth". The homedir of the user running pulse is automatically
prepended to non-absolute paths.
auth-cookie-enabled
New in 0.9.12: enable/disable auth-cookie authentication, takes a boolean value (0 or 1). Defaults to 1.
cookie
The old name for auth-cookie. Don't use this, it's only here for compatibility with versions before 0.9.12.
auth-ip-acl (only for -tcp}
New in 0.9.3: A semicolon separated list of IP address range to which anonymous access is allowed.
Example: auth-ip-acl=[Link];[Link]/24;[Link]/8

module-native-protocol-{unix,tcp}

The native protocol of PulseAudio.

See module-cli-protocol-{unix,tcp} for more information about the two possible suffixes of this module.

In addition to the options supported by module-cli-protocol-*, this module supports:

auth-anonymous
If set to true, no authentication is required to connect to the service
auth-group (only for -unix)
Members of the specified unix group may access the server without further authentication. If the daemon is running in system-wide mode ( --system passed
when starting up) defaults to pulse-access, otherwise is disabled.
auth-group-enable (only for -unix)
Enable/disable auth-group authentication, takes a boolean value. If auth-group= is specified or started in system-wide mode defaults to true, otherwise false.
auth-cookie
Path to the cookie file. If the path is relative, the cookie will be searched from the normal configuration directories. The cookie file contains random data that
is used as a shared secret between the server and the clients.
auth-cookie-enabled
Enable/disable auth-cookie authentication, takes a boolean value. Defaults to true.
cookie
The old name for auth-cookie. Don't use this, it's only here for compatibility with versions before 0.9.12.
auth-ip-acl (only for -tcp}
A semicolon separated list of IP address range to which anonymous access is allowed. Example: auth-ip-acl=[Link];[Link]/24;[Link]/8
srbchannel (only for -unix)
Enable/disable the srbchannel communication mechanism, takes a boolean value.

module-native-protocol-fd

This is used internally when auto spawning a new daemon. Don't use it directly.

11 of 24 08/07/2017 12:26 PM
Modules [Link]

module-http-protocol-tcp

A proof-of-concept HTTP module, which can be used to introspect the current status of the PulseAudio daemon using HTTP. Just load this module and point your browser
to [Link] This module takes the same arguments as module-cli-protocol-tcp.

Saving/restoring settings
module-default-device-restore

Since 0.9.7. Automatically restore the default sink and source (configuration is saved in a file)

module-card-restore

Automatically restore profile of cards.

module-device-restore

Since 0.9.11. Automatically restore the volume/mute state of devices (configuration is saved in a GDBM database)

restore_volume
Restore volume (default to true)
restore_muted
Restore mute state (default to true)

Since 0.9.16

restore_port
Restore port (default to true)

module-stream-restore

Since 0.9.11. Automatically restore the volume/mute/device state of streams (configuration is saved in a GDBM database)

restore_volume
Restore volume (default to true)
restore_muted
Restore mute state (default to true)
restore_device
Restore the selected sink/source (default to true)
on_hotplug
Since 0.9.16. Recheck streams when new device becomes available. (default to true)
on_rescue
Since 0.9.16. Recheck streams when device becomes unavailable. (default to true)
fallback_table
Since 2.0. File name for a fallback table, containing stream-restore entries (with volume only). The file name can be absolute or relative to the configuration
directory. When module-stream-restore is loaded, each fallback entry is saved to the database if that entry didn't already exist. The original purpose was to
have a way to configure initial volumes for streams already before the first boot. If this argument is not specified, "[Link]" will be loaded if it
happens to exist (by default it doesn't). The file format is explained in the example file.

module-device-manager

Since 0.9.20. Implement a history of devices and a per-role device priority list routing scheme. This module was primary written to enable the routing system employed

12 of 24 08/07/2017 12:26 PM
Modules [Link]

in KDE to work at a lower level. It is conditionally loaded via the start-pulsaudio-kde script which only runs when working with KDE sessions. The longer term goal for
this module is for the functionality to be integrated into PA more fully. See Software/PulseAudio/RFC/PriorityRouting

do_routing
Enable the routing mode.

X Window System
module-x11-bell

Intercepts X11 bell events and plays a sample from the sample cache on each occurence.

display
X11 display to connect to. If ommited defaults to the value of $DISPLAY
sample
The sample to play. If omitted defaults to x11-bell. Note that this is not a file name, but a name that is given to the sample when the sample is loaded. This
module doesn't load any sample itself. Instead, use load-sample with pacmd or in [Link].
sink
Name of the sink to play the sample on. If omitted defaults to the default sink.

module-x11-publish

Publishes the access credentials to the PulseAudio server in the X11 root window. The following properties are used: PULSE_SERVER, POYLP_SINK, PULSE_SOURCE,
PULSE_COOKIE. This is very useful when using SSH or any other remote login tool for logging into other machines and getting audio playback to your local speakers.
The PulseAudio client libraries make use of this data automatically. Instead of using this module you may use the tool pax11publish which may be used to access, modify
and import credential data from/to the X11 display.

display
X11 display to connect to. If omitted defaults to the value of $DISPLAY
sink
Name of the default sink. If omitted this property isn't stored in the X11 display.
source
Name of the default source. If omitted this property isn't stored in the X11 display.
cookie
Name of the cookie file of the cookie to store in the X11 display. If omitted the cookie of an already loaded protocol module is used.

module-x11-xsmp

Since 0.9.7. Register to the X11 session manager

session_manager
Session manager to connect to. If omitted defaults to the value of $SESSION_MANAGER
display
X11 display to connect to. If omitted defaults to the value of $DISPLAY

Volume Control
Common options to both modules

sink
The sink to control

13 of 24 08/07/2017 12:26 PM
Modules [Link]

Since 1.0

volume_limit
Volume limit.
volume_step
Volume change step size

module-mmkbd-evdev

Adjust the volume of a sink when the special multimedia buttons of modern keyboards are pressed.

device
Linux input device ("evdev", defaults to /dev/input/event0)

module-lirc

Adjust the volume of a sink when the volume buttons of an infrared remote control are pressed (through LIRC).

config
The LIRC configuration file
appname
The application name to pass to LIRC (defaults to PulseAudio)

Here is a sample ~/.lircrc entry configured to forward signals to PulseAudio. Note that you may have to change the button names (Vol_Up, Vol_Down...) to match those
in your /etc/lirc/[Link].

begin
prog = PulseAudio
remote = *
button = Vol_Up
config = volume-up
repeat = 5
end

begin
prog = PulseAudio
remote = *
button = Vol_Down
config = volume-down
repeat = 5
end

begin
prog = PulseAudio
remote = *
button = Mute
config = mute-toggle
end

Available configs include: volume-up, volume-down, mute, mute-toggle and reset.

Bluetooth
module-bluetooth-discover

Detects available bluetooth audio devices using BlueZ.

14 of 24 08/07/2017 12:26 PM
Modules [Link]

Some hardware uses alsa devices for the SCO link (used by the HSP/HFP and HFGW profiles). This is called the "SCO over PCM" mode. For such hardware, the alsa sink
and source need to be specified with the "sco_sink" and "sco_source" arguments. This feature is only available with BlueZ 4.

headset
The backend for HSP/HFP. Supported values: "native", "ofono", "auto". The native backend doesn't have any extra dependencies. The ofono backend depends
on oFono. Available with BlueZ 5 only.
sco_sink
Name of the alsa sink that should be used in the "SCO over PCM" mode. Available with BlueZ 4 only.
sco_source
Name of the alsa source that should be used in the "SCO over PCM" mode. Available with BlueZ 4 only.

module-bluetooth-policy

Takes care of any bluetooth specific policy. Currently two features are implemented:

Switch the card profile automatically to "hfgw" or "a2dp_source" when the remote end starts playing audio.

Load module-loopback automatically for A2DP and HFGW sources, so that the received audio is automatically played back to some output.

Supported arguments:

a2dp_source
A boolean argument controlling whether the module-loopback loading should be enabled for A2DP sources.
hfgw
A boolean argument controlling whether the module-loopback loading should be enabled for HFGW sources.

module-bluetooth-proximity

Since 0.9.11 Bluetooth proximity volume control

sink
The sink to adjust the volume
hci
hci device

RTP/SDP/SAP Transport
PulseAudio can stream audio data to an IP multicast group via the standard protocols RTP, SAP and SDP (RFC3550, RFC3551, RFC2327, RFC2327). This can be used for
multiple different purposes: for sharing a single microphone on multiple computers on the local LAN, for streaming music from a single controlling PC to multiple PCs
with speakers or to implement a simple "always-on" teleconferencing solution.

The current implementation is designed to be used exclusively in local area networks, though Internet multicasting is theoretically supported. Only uncompressed audio
is supported, hence you won't be able to multicast more than a few streams at the same time over a standard LAN.

PulseAudio implements both a sender and a receiver for RTP traffic. The sender announces itself via SAP/SDP on the same multicast group as it sends the RTP data to.
The receiver picks up the SAP/SDP announcements and creates a playback stream for each session. Alternatively you can use any RTP capable client to receive and play
back the RTP data (such as mplayer, see How To Listen To The Rtp Stream).

module-rtp-send

This is the sender side of the RTP/SDP/SAP implementation. It reads audio data from an existing source and forwards it to the network encapsulated in RTP. In addition
it sends SAP packets with an SDP session description.

15 of 24 08/07/2017 12:26 PM
Modules [Link]

In combination with the monitor source of module-null-sink you can use this module to create an RTP sink.

source
The source to read the audio data from.
format
The sample format.
channels
The number of channels.
rate
The sample rate.
destination_ip
Since 4.0. Destination multicast group for both RTP and SAP packets.
source_ip
Since 4.0. On a multi-homed system, you may wish RTP to be used only on a specific interface. The interface can be selected by specifying the source IP
address.
port
Destination port number of the RTP traffic. Keep in mind that the RFC suggests to use only even port numbers for RTP traffic.
mtu
Maximum payload size for RTP packets.
loop
Takes a boolean value, specifying whether locally generated RTP traffic should be looped back to the local host.
ttl
The "time to live" value.
inhibit_auto_suspend
Since 5.0. The policy for interacting with the automatic source suspension logic. module-suspend-on-idle suspends devices when no streams are connected to
them, or if all connected streams are marked to be ignored by module-suspend-on-idle. This argument controls whether and when the stream that module-
rtp-send creates is marked to be ignored by module-suspend-on-idle. There are three options: "always", "never" and "only_with_non_monitor_sources". The
"always" option prevents module-suspend-on-idle from ever suspending the source, the "never" option allows module-suspend-on-idle to always suspend the
source and the "only_with_non_monitor_sources" option allows module-suspend-on-idle to suspend monitor sources, but not "regular" sources. The important
case where this argument really matters is when module-rtp-send is connected to a monitor source. You should choose the "always" option if you want to send
silence to the network when nothing is playing to the monitored sink. You should choose the "only_with_non_monitor_sources" option if you want to pause the
RTP stream when nothing is playing to the monitored sink. The "never" option is not really useful, because it doesn't make sense to suspend non-monitor
sources like microphones. The "never" option only exists as a logical complement the "always" option - if you find the "never" option useful anyway, we'd be
interested to hear about your use case.

module-rtp-recv

This is the receiver side of the RTP/SDP/SAP implementation. It picks up SAP session announcements and creates an RTP playback stream for each.

In combination with module-null-sink you can use this module to create an RTP source.

sink
The sink to connect to. If omitted defaults to the default sink.
sap_address
The address used to listen for SAP announcements, defaults to [Link]. It can be either a multicast group or a unicast address.
latency_msec
The desired latency due to local buffering (the network latency and buffering at the sender's end are beyond PulseAudio's control and knowledge, so they
aren't counted here).

RAOP Sink (Wireless Network Sound aka Apple Airtunes)

PulseAudio can stream audio data to products that support the RAOP protocol.

16 of 24 08/07/2017 12:26 PM
Modules [Link]

module-raop-discover

mDNS/DNS-SD Service Discovery of RAOP devices

module-raop-sink

The main module used to create a virtual output device which pipes all audio to the RAOP device.

sink_name
The name of the sink (see Modules)
server
The server to connect to
sink_properties, format, rate, channels
All supported as per Modules

JACK Connectivity
PulseAudio can be hooked up to a JACK Audio Connection Kit server which is a specialized sound server used for professional audio production on Unix/Linux. Both a
PulseAudio sink and a source are available. For each channel a port is created in the JACK server.

module-jack-sink

This module implements a PulseAudio sink that connects to JACK and registers as many output ports as requested.

sink_name
The name for the PulseAudio sink. If omitted defaults to jack_out.
server_name
The JACK server to connect to. If omitted defaults to the default server.
client_name
The client name to tell the JACK server. If omitted defaults to PulseAudio.
channel_map channels
Number of channels to register. If omitted defaults to the number of physical playback ports of the JACK server.
connect
Takes a boolean value. If enabled (the default) PulseAudio will try to connect its ports to the physical playback ports of the JACK server

module-jack-source

This module implements a PulseAudio source that connects to JACK and registers as many input ports as requested. Takes the same arguments as module-jack-sink,
except for sink_name which is replaced by source_name (with a default of jack_in) for obvious reasons.

module-jackdbus-detect

This module automatically adds JACK sinks and sources whenever the JACK server is started. For this to work, you need to use JACK 2, and enable JACK's D-Bus
interface.

channels
The number of channels to create for both module-jack-sink and module-jack-source. If omitted, the sink will use the number of physical output ports and the
source will use the number of physical input ports registered in the JACK server.
connect
Takes a boolean value. If enabled (the default) PulseAudio will try to connect its ports to the physical playback ports of the JACK server.

17 of 24 08/07/2017 12:26 PM
Modules [Link]

Filters
These modules create a virtual sink and/or source on top of a given sink and source and filter the data flowing through.

module-echo-cancel

Used to perform acoustic echo cancellation between a designated sink and source. Since 1.0

source_name
Name to give the virtual source that is created
source_properties
Properties to set on the virtual source
source_master
Name of the source to filter
sink_name
Name to give the virtual sink that is created
sink_properties
Properties to set on the virtual sink
sink_master
Name of sink to filter
autoloaded
Set if this module is being loaded automatically. Don't set this manually unless you know what you're doing.
use_volume_sharing
Whether to use volume sharing with master sink/source
adjust_time
How often to readjust sync between sink and source (in seconds)
adjust_threshold
Since 2.0. How much drift to readjust after (in milliseconds)
format
The sample format of the virtual sink and source.
rate
The sample rate of the virtual sink and source.
channels
The number of channels of the virtual sink and source.
channel_map
The channel map of the virtual sink and source.
use_master_format
Use format/rate/channels from the master source and sink
aec_method
Specific AEC implementation to use ("speex", "webrtc", "adrian" (not a very good canceller) or "null").

aec_args

Parameters for the AEC engine. In case there are multiple arguments, enclose the value in quotes and separate the arguments with spaces, like this:
aec_args="arg1=value1 arg2=value2". The set of supported arguments vary depending on the selected AEC method.
speex:
(to be documented)

webrtc:

(most arguments are yet to be documented)

beamforming

18 of 24 08/07/2017 12:26 PM
Modules [Link]

A boolean, set to true to enable beamforming. When enabling this, the "mic_geometry" argument has to be given too. The "target_direction"
argument can be used to configure the beamforming target direction.

mic_geometry

The microphone positions for beamforming. The value is a list of numbers (coordinates). For example, a microphone array containing two mics would
require six numbers: "x1,y1,z1,x2,y2,z2". In that example, the first three numbers specify the coordinates of the first mic relative to the center of the
microphone array, and the last three numbers specify the coordinates of the second mic. All distances are given in meters.

'x' is the horizontal coordinate, with positive values being to the right from the mic array's perspective.

'y' is the depth coordinate, with positive values being in front of the array.

'z' is the vertical coordinate, with positive values being above the array.

As an example, if you have a webcam with 2 microphones 8cm apart, and you want to point it forwards, you could use

pactl load-module module-echo-cancel use_master_format=1 aec_method='webrtc' aec_args='"beamforming=1 mic_geometry=-0.04,0,0,0.04,0,0"'

target_direction

The target position relative to the centre of the mic array, for beamforming. The value is a list of three numbers (a spherical point): "a,e,r". 'a' is the
azimuth of the target in radians. Zero radians azimuth points to the right of the mic array, and positive angles move in a counter-clockwise direction.
'e' is the elevation of the target in radians. Zero radians elevation means that the target is on the same level horizontally as the center of the array,
and positive angles go upwards. 'r' is the radius, i.e. the distance from the center of the array (in meters).

adrian:

(to be documented)
null:
(to be documented)
save_aec
If set, saves AEC data in /tmp/aec_*

module-equalizer-sink

General purpose equalizer that can be applied over a given sink. Since 1.0

sink_name
Name to give the virtual sink that is created
sink_properties
Properties to set on the virtual sink
sink_master
Name of sink to filter
autoloaded
Set if this module is being loaded automatically. Don't set this manually unless you know what you're doing.
use_volume_sharing
Whether to use volume sharing with master sink/source

module-ladspa-sink

Adds signal processing (for example equalizing) to a sink with a LADSPA plugin.

The module shows up as a separate sink.

19 of 24 08/07/2017 12:26 PM
Modules [Link]

sink_name
Name for this sink.
sink_properties
Extra properties to be stored in the sink's property list.
master
The sink where the processed audio is forwarded to.
channels, rate, channel_map
Normal sink parameters. It's best to leave these unspecified, so that the master sink parameters will be used.
plugin
The name of the .so file that contains the desired filter without the ".so" part. Specify only the file name, not the full directory path. The directories where the
plugin files are searched from can be specified with the environment variable LADSPA_PATH. Multiple directories can be specified using colon (:) as the
separator. If the environment variable isn't set, "$libdir/ladspa:/usr/local/lib/ladspa:/usr/lib/ladspa" is used instead ($libdir is specified at build time, so the
default search path should include the directory where your distribution installs LADSPA plugins).
label
One plugin file may contain multiple plugins, which are identified by a label. Specify it here.
control
If the plugin has control input ports, you have to specify their values here. That is done by simply listing the numeric values using comma as the separator.
Default values can be used by leaving the number out. Examples: Plugin with five control ports, leaving the third to the default value: control=0.34,-2.3,,0.00346,5
Plugin with three control ports, leaving all to the default values: control=,,
input_ladspaport_map
Comma separated list of input LADSPA audio port names. The list is matched with the sink channel map so that each LADSPA port in the list is assigned for
the corresponding channel channel map. If this argument is not given, the ports are assigned in the order that the plugin lists them.
output_ladspaport_map
Comma separated list of output LADSPA audio port names. The list is matched with the sink channel map so that each LADSPA port in the list is assigned for
the corresponding channel channel map. If this argument is not given, the ports are assigned in the order that the plugin lists them.

An example: adding an equalizer to a normal alsa sink (on Debian the mbeq plugin is in the swh-plugins package).

load-module module-ladspa-sink sink_name=ladspa_out master=alsa_out plugin=mbeq_1197 label=mbeq control=11.621622,10,4.594594,2.702703,0,0,-1.621622,-0.270270,-5.405406,-3.513514,-8.648648,-5.675676,-4.0

The control values can't be modified at run-time, so it can be a problem to figure out good control values for the plugin. The writer of this documentation used JACK
Rack to find the values. This is a good solution if you already are familiar with Jack, but if you're not, this is one more thing to learn. If someone knows a handier way to
fiddle with the parameters, please edit this page.

Control output ports are ignored.

module-virtual-surround-sink

Simulates surround sound when using headphones.

The module shows up as a separate sink. You can set the following parameters:

sink_name
Name for this sink.
sink_properties
Properties to set on the virtual sink.
master
The sink where the processed audio is forwarded to.
hrir
The hrir file that should be used. The module will convolve the input signal with the HRIR to create the output signal.

Example:

20 of 24 08/07/2017 12:26 PM
Modules [Link]

load-module module-virtual-surround-sink sink_name=vsurround hrir=/home/user/.[Link] sink_properties=[Link]=VirtualSurround

You might want to put this line in ~/.config/pulse/[Link] since the HRIR file for best results can be different for every user.

Some HRIR files can be found here and here. The HRIR file from the first link was recorded using a dummy head. It was designed to work well for most people. The
second link contains many HRIR files that where recorded using real heads. You should play back the files in the demos folder. Then, you should decide which gives you
the best impression of a noise moving around your head in a circle. You can find the corresponding HRIR file for this module in the hrirs folder.

Miscellaneous
module-sine

Creates a sink input and generates a sine waveform stream.

sink
The sink to connect to. If omitted defaults to the default sink.
frequency
The frequency to generate in Hertz. Defaults to 440.

module-sine-source

Creates a source and generates a sine waveform stream.

source_name
Name for the source. (defaults to sine_input)
rate
Sample rate for the source.
frequency
The frequency to generate in Hertz. Defaults to 440.

module-esound-compat-spawnfd

This is a compatibility module for libesd based autospawning of PulseAudio. Don't use it directly.

module-esound-compat-spawnpid

This is a compatibility module for libesd based autospawning of PulseAudio. Don't use it directly.

module-match

Adjust the volume of a playback stream automatically based on its name.

table
The regular expression matching table file to use (defaults to ~/.pulse/[Link])

The table file should contain a regexp and volume on each line, separated by spaces. An example:

^sample: 32000

The volumes of all streams with titles starting with sample: are automatically set to 32000. (FYI: All sample cache streams start with sample:)

21 of 24 08/07/2017 12:26 PM
Modules [Link]

module-udev-detect

Since 0.9.16. Detects ALSA audio devices on the system using udev.

tsched
Enable timer based scheduling?
tsched_buffer_size
Since 4.0. Buffer size in bytes when timer based scheduling is enabled.
fixed_latency_range
Since 2.0. Boolean. Normally when there's an alsa underrun or overrun, and timer based scheduling is used, the alsa sink or source will raise the minimum
latency that applications can get to avoid further underruns or overruns. If this option is enabled, the minimum latency will stay constant even if underruns or
overruns occur.
ignore_dB
Ignore the decibel information that ALSA provides?
deferred_volume
Since 1.0. Synchronize sw and hw volume changes?
use_ucm
Since 4.0. PulseAudio uses ALSA UCM configuration by default if it's available. This argument can be used to disable UCM.

module-detect

This module is deprecated on systems where udev is available. Please use module-udev-detect instead.

Automatically detect the available sound hardware and load modules for it. Supports OSS, ALSA, Solaris and Win32 output drivers, and the information is taken directy
from them, not through udev.

Do not use this together with module-udev-detect!

The parameter:

just-one
If set to 1 the module will only try to load a single sink/source and than stop.

module-zeroconf-publish

Publish all local sinks/sources using mDNS Zeroconf. For more information, see Network Setup.

module-zeroconf-discover

Discover sinks/sources on other PulseAudio servers using mDNS Zeroconf.

module-rescue-streams

Automatically route a stream whose sink has become unavailable (e.g. USB hw plugged out) to another working sink.

module-systemd-login

Since 2.0. Create a client for each login session of this user.

This module doesn't do anything on systems that don't use systemd, so this module can be loaded at the same time with module-console-kit.

module-console-kit

22 of 24 08/07/2017 12:26 PM
Modules [Link]

Since 0.9.11. Create a client for each ConsoleKit session of this user

This module doesn't do anything on systems that use systemd, so this module can be loaded at the same time with module-systemd-login.

module-position-event-sounds

Since 0.9.11. Position event sounds between L and R depending on the position on screen of the widget triggering them.

module-always-sink

Since 0.9.11. Always keeps at least one sink loaded even if it's a null one

sink_name
The name for the new virtual sink.

module-suspend-on-idle

Since 0.9.11. Disconnects sinks and sources from their backend after a predetermined amount of idle time. Idle time is accumulated when the sink/source in question
is not connected to any streams.

Advantages: Saves power. ALSA uses considerably more CPU cycles when pulseaudio has to send empty data to the soundcard during idle. If you don't plan to have an
active stream all the time, set the timer to a low value for best power savings.

Disadvantages: When pulseaudio gives up the backend, and the backend is not capable of mixing, errant applications can grab the sound device and hold exclusive
control over it, making pulseaudio stop working. If pulseaudio does not give up the backend, errant applications won't be able to play sound, but they will not disrupt
pulseaudio's operation either. This scenario is possible 99% of the time, since most users run an ALSA sink/source without a card that has software mixing. An "errant
application" would, for example, try to open hw:0 or front:0 rather than the 'default' ALSA device.

timeout
Time, in seconds, which must elapse before a sink or source is deemed idle.

module-loopback

Since 0.9.16. This allows one to route audio from a source directly back to a sink.

source
The name of the input source to connect to. If not specified the source will be picked automatically. You can use a tool like pavucontrol to move the loopback
stream to the right source.
sink
The name of the sink the audio is forwarded to. If not specified the sink will be picked automatically.
adjust_time
How often to readjust the sample rates in seconds. Defaults to 10.
latency_msec
The desired latency in milliseconds, from 1 to 2000. Defaults to 200. (Note that this is only a friendly request, the actually latency might be higher or lower
thatn this value)
format
The sample format. Defaults to that of specified sink.
rate
The sample rate. Defaults to that of specified sink.
channels
Number of source channels to use. Defaults to that of specified sink.
channel_map

23 of 24 08/07/2017 12:26 PM
Modules [Link]

List of the channels to connect to the sink.

sink_input_properties
Since 1.0. Property list for the playback stream object.
source_output_properties
Since 1.0. Property list for the capture stream object.
source_dont_move
Since 1.0. Takes a boolean value. Disallows moving the capture stream to some other than the initial source. Defaults to "false".
sink_dont_move
Since 1.0. Takes a boolean value. Disallows moving the playback stream to some other than the initial sink. Defaults to "false".
remix
Since 1.0. Takes a boolean value. If the channel map of the capture stream doesn't match the source's channel map, or the channel map of the playback
stream doesn't match the sink's channel map, the mismatch has to be handled somehow. If remixing isn't disabled in the global server configuration, by default
the audio will get remixed. This parameter can be used to disable remixing for the loopback streams (but if remixing is disabled in the global server
configuration, this parameter can't be used for forcing remixing - setting this parameter simply has no effect at all).

module-switch-on-connect

Whenever a new sink or source appears, this module will switch the default sink/source to be the new sink/source, and will move all currently running streams to the
new sink/source.

only_from_unavailable
Takes a boolean value. If set to true, the device switch is only done if the current default device is currently marked as unavailable.

module-role-ducking

This module lowers the volume of less important streams when a more important stream appears, and raises the volume back up once the important stream has finished
(this is called "ducking"). The decision whether a stream has high or low priority is made based on the stream role (the [Link] property). By default, "music" and
"video" streams are ducked, and "phone" streams trigger the ducking.

trigger_roles
Comma separated list of roles that will trigger ducking.
ducking_roles
Comma separated list of roles that will be ducked.
global
A boolean. If true, ducking will be applied to all streams that have a ducking role. If false, ducking will be applied only to streams that are connected to the
same device as the triggering stream.
volume
Attenuation to be used while ducking. The value can be given either as a percentage (for example, "40%"), in decibels (for example, "-20dB") or as a plain
integer between 0 and 65536 (this is the representation that PulseAudio uses for volume internally).

module-allow-passthrough

Since 10.0. This module ensures that passthrough streams are always allowed to play on sinks. The default policy in PulseAudio is to only allow exclusive access if
nothing else is currently using the sink. With this module, all the existing streams are muted (by being re-routed to the null sink) when a passthrough stream comes in,
allowing the passthrough stream to exclusively use the sink.

This is particularly useful with media centers and HTPC boxes (e.g. Kodi media center) where we usually always want to be able to start a video even if an external
notification sound happened to be playing at the same time.

Last edited Fri Aug 4 09:35:24 2017

24 of 24 08/07/2017 12:26 PM