Simple Command Line Language

PulseAudio provides a simple command line language used by configuration scripts as well as the modules module-cli and module-cli-protocol-{unix,tcp}. Empty lines and lines beginning with a hashmark (#) are silently ignored. Several commands are supported:

Miscellaneous Commands

help

Show a quick help on the commands available.

exit

Terminate the daemon. If you want to terminate a CLI connection ("log out") you might want to use C-d.

Status Commands

list-modules

Show all currently loaded modules with their arguments.

list-sinks/list-sources

Show all currently registered sinks (resp. sources).

list-clients

Show all currently active clients.

list-sink-inputs/list-sink-outputs

Show all currently active inputs to sinks (resp. outputs of sources).

stat

Show some simple statistics about the allocated memory blocks and the space used by them.

info

A combination of all status commands described above. ls and list are synonyms for info.

Module Management

load-module

Load a module specified by its name and arguments. For most modules it is OK to be loaded more than once.

unload-module

Unload a module specified by its index in the module list as returned by modules.

Configuration Commands

set-sink-volume/set-source-volume

Set the volume of the specified sink or source. You may specify the sink/source either by its index in the sink/source list or by its name. The volume should be an integer value greater or equal than 0 (= muted). Volume 65536 (0x10000) is normal volume, values greater than this amplify the audio signal (with clipping).

set-sink-mute/set-source-mute

Mute or unmute the specified sink our source. You may specify the sink/source either by its index or by its name. The mute value is either 0 or 1.

set-sink-input-volume

Set the volume of a sink input specified by its index the the sink input list. The same volume rules apply as with sink_volume.

set-default-sink/set-default-source

Make a sink (resp. source) the default. You may specify the sink (resp. ssource) by its index in the sink (resp. source) list or by its name.

Sample Cache

list-samples

Lists the contents of the sample cache.

play-sample

Play a sample cache entry to a sink. Expects the sample name and the sink name as arguments.

remove-sample

Remove an entry from the sample cache. Expects the sample name as argument.

load-sample

Load an audio file to the sample cache. Expects the file name to load and the desired sample name as arguments.

load-sample-lazy

Create a new entry in the sample cache, but don't load the sample immediately. The sample is loaded only when it is first used. After a certain idle time it is freed again. Expects the the desired sample name and file name to load as arguments.

load-sample-dir-lazy

Load all entries in the specified directory into the sample cache as lazy entries. A shell globbing expression (e.g. *.wav) may be appended to the path of the directory to add.

Module Autoloading

list-autoload

Lists all currently defined autoloading entries.

add-autoload-sink/add-autoload-source

Adds an autoloading entry for a sink (resp. source). Expects the sink name (resp. source name), the module name and the module arguments as arguments.

remove-autoload-sink/remove-autoload-source

Remove an autoloading entry. Expects the sink name (resp. source name) as argument.

Miscellaneous Commands

play-file

Play an audio file to a sink. Expects the file name and the sink name as argumens.

dump

Dump the daemon's current configuration in CLI commands.

Killing Clients/Streams

kill-client

Remove a client forcibly from the server. There is no protection that the client reconnects immediately.

kill-sink-input/kill-source-output

Remove a sink input (resp. source output) forcibly from the server. This will not remove the owning client or any other streams opened by the client from the server.

Meta Commands

In addition the the commands described above there a few meta directives supported by the command line interpreter:

.include

Executes the commands from the specified script file.

.fail/.nofail

Enable (resp. disable) that following failing commands will cancel the execution of the current script file. This is a ignored when used on the interactive command line.

.verbose/.noverbose

Enable (resp. disable) extra verbosity.

Example Configuration Script

Mark the following script as executable (chmod +x) and run it for a sensible PulseAudio configuration.

#!/usr/bin/pulseaudio -nF

# Create autoload entries for the device drivers
add-autoload-sink output module-alsa-sink device=plughw:0,0 rate=48000 sink_name=output
add-autoload-sink output2 module-oss device=/dev/dsp1 record=0 sink_name=output2
add-autoload-sink combined module-combine master=output slaves=output2 sink_name=combined

add-autoload-source input module-alsa-source device=hw:1,0 source_name=input

# Load several protocols
load-module module-esound-protocol-unix
load-module module-simple-protocol-tcp
load-module module-native-protocol-unix
load-module module-cli-protocol-unix

# Make some devices default
set-default-sink combined
set-default-source input

# Don't fail if the audio files referred to below don't exist
.nofail

# Load an audio to the sample cache for usage with module-x11-bell
load-sample-lazy  /usr/share/sounds/KDE_Notify.wav x11-bell
load-module module-x11-bell sample=x11-bell

# Play a welcome sound
play-file /usr/share/sounds/startup3.wav combined