Go to main content

man pages section 1: User Commands

Exit Print View

Updated: Wednesday, February 9, 2022

pulseaudio (1)


pulseaudio - The PulseAudio Sound System


pulseaudio [options]

pulseaudio --help

pulseaudio --version

pulseaudio --dump-conf

pulseaudio --dump-modules

pulseaudio --dump-resample-methods

pulseaudio --cleanup-shm

pulseaudio --start

pulseaudio --kill

pulseaudio --check


pulseaudio(1)               General Commands Manual              pulseaudio(1)

       pulseaudio - The PulseAudio Sound System

       pulseaudio [options]

       pulseaudio --help

       pulseaudio --version

       pulseaudio --dump-conf

       pulseaudio --dump-modules

       pulseaudio --dump-resample-methods

       pulseaudio --cleanup-shm

       pulseaudio --start

       pulseaudio --kill

       pulseaudio --check

       PulseAudio is a networked low-latency sound server for Linux, POSIX and
       Windows systems.

       -h | --help
              Show help.

              Show version information.

              Load the daemon  configuration  file  daemon.conf  (see  below),
              parse  remaining  configuration  options on the command line and
              dump the resulting daemon configuration, in  a  format  that  is
              compatible with daemon.conf.

              List  available  loadable  modules.  Combine  with -v for a more
              elaborate listing.

              List available audio resamplers.

              Identify  stale  PulseAudio  POSIX  shared  memory  segments  in
              /dev/shm  and  remove  them if possible. This is done implicitly
              whenever a new daemon starts up or a client tries to connect  to
              a daemon. It should normally not be necessary to issue this com-
              mand by hand. Only available on systems with POSIX shared memory
              segments  implemented  via  a  virtual  file  system  mounted to
              /dev/shm (e.g. Linux).

              Start PulseAudio if it is not running  yet.  This  is  different
              from  starting PulseAudio without --start which would fail if PA
              is already running. PulseAudio is guaranteed to  be  fully  ini-
              tialized when this call returns. Implies --daemonize.

       -k | --kill
              Kill  an  already  running PulseAudio daemon of the calling user
              (Equivalent to sending a SIGTERM).

              Return 0 as return code when the PulseAudio  daemon  is  already
              running for the calling user, or non-zero otherwise. Produces no
              output on the console except for errors to stderr.

              Note that a non-zero return value doesn't necessarily mean  that
              PulseAudio  is not usable. Even if the server is not running, it
              may get  automatically  started  via  PulseAudio's  autospawning
              mechanism  or  systemd's  socket  activation, or the environment
              might be such that checking  for  processes  doesn't  work  (for
              example,  the  running  server might not show up in a container,
              even if the server is accessible via a socket).  Also  disabling
              PID files with --use-pid-file=no prevents --check from detecting
              running servers.

              A more robust check in most situations would be  to  try  estab-
              lishing a client connection to the server. Unfortunately there's
              currently no --check-connection option to replace  --check,  but
              running "pactl info" could be a pretty good substitute.

              Run  as  system-wide  instance  instead of per-user. Please note
              that this disables certain features of PulseAudio and is  gener-
              ally  not  recommended  unless  the  system knows no local users
              (e.g. is a thin client). This feature needs  special  configura-
              tion  and a dedicated UNIX user set up. It is highly recommended
              to combine this with --disallow-module-loading (see below).

       -D | --daemonize[=BOOL]
              Daemonize after startup, i.e. detach  from  the  terminal.  Note
              that  when  running as a systemd service you should use --daemo-
              nize=no for systemd notification to work.

              Fail startup when any of the commands specified in  the  startup
              script default.pa (see below) fails.

              Try to acquire a high Unix nice level. This will only succeed if
              the calling user has a non-zero RLIMIT_NICE resource  limit  set
              (on systems that support this), or we're configured to be run as
              system daemon (see --system above). It is recommended to  enable
              this, since it is only a negligible security risk (see below).

              Try  to  acquire  a  real-time  scheduling  for PulseAudio's I/O
              threads. This will only succeed if the calling user has  a  non-
              zero  RLIMIT_RTPRIO  resource limit set (on systems that support
              this), or rtkit is available and  allows  PulseAudio  to  enable
              real-time  scheduling,  or we are configured to be run as system
              daemon (see --system above).

              Disallow module loading after startup. This is a  security  fea-
              ture since it disallows additional module loading during runtime
              and on user request. It is highly recommended when  --system  is
              used  (see  above).  Note however, that this breaks certain fea-
              tures like automatic module loading on hot plug.

              Disallow user requested exit

              Terminate the daemon after the last client quit and this time in
              seconds  passed.  Use  a negative value to disable this feature.
              Defaults to 20.

              When PulseAudio runs in the per-user mode and  detects  a  login
              session,  then  any  positive  value  will be reset to 0 so that
              PulseAudio will terminate  immediately  on  logout.  A  positive
              value therefore has effect only in environments where there's no
              support for login session tracking (or if the user is logged  in
              without  a  session spawned, a.k.a. lingering). A negative value
              can still be used to disable any automatic exit.

              When PulseAudio runs in  the  system  mode,  automatic  exit  is
              always disabled, so this option does nothing.

              Unload  autoloaded samples from the cache when they haven't been
              used for the specified number of seconds.

              If an argument is passed, set the log  level  to  the  specified
              value, otherwise increase the configured verbosity level by one.
              The log levels are numerical  from  0  to  4,  corresponding  to
              error,  warn,  notice, info, debug. Default log level is notice,
              i.e. all log messages with lower log levels are printed:  error,
              warn, notice.

       -v | --verbose
              Increase  the configured verbosity level by one (see --log-level
              above). Specify multiple times to increase  log  level  multiple

              Specify  the  log target. If set to auto (which is the default),
              then logging is directed to syslog when --daemonize  is  passed,
              otherwise  to  STDERR.  If set to journal logging is directed to
              the systemd journal. If set to file:PATH, logging is directed to
              the  file  indicated by PATH. newfile:PATH is otherwise the same
              as file:PATH, but existing files are never overwritten.  If  the
              specified  file  already  exists,  a suffix is added to the file
              name to avoid overwriting.

              Show source code location in log messages.

              Show timestamps in log messages.

              When FRAMES is greater than 0, log  for  each  message  a  stack
              trace up to the number of specified stack frames.

       -p | --dl-search-path=PATH
              Set the search path for dynamic shared objects (plugins).

              Use  the  specified  resampler  by default (See --dump-resample-
              methods above for possible values).

              Create a PID file. If this options is disabled it is possible to
              run multiple sound servers per user.

              Do not install CPU load limiter on platforms that support it. By
              default, PulseAudio will terminate itself when it  notices  that
              it  takes  up  too much CPU time. This is useful as a protection
              against system lockups when real-time scheduling  is  used  (see
              below).  Disabling  this  mechanism  is  useful  when  debugging
              PulseAudio with tools like valgrind(1) which  slow  down  execu-

              PulseAudio  clients  and  the server can exchange audio data via
              POSIX or memfd shared memory segments (on systems  that  support
              this).  If disabled PulseAudio will communicate exclusively over
              sockets. Please note that data transfer via shared  memory  seg-
              ments  is always disabled when PulseAudio is running with --sys-
              tem enabled (see above).

              PulseAudio clients and the server can exchange  audio  data  via
              memfds  - the anonymous Linux Kernel shared memory mechanism (on
              kernels that support this). If disabled PulseAudio will communi-
              cate via POSIX shared memory.

       -L | --load="MODULE ARGUMENTS"
              Load the specified plugin module with the specified arguments.

       -F | --file=FILENAME
              Run  the  specified script on startup. May be specified multiple
              times to specify multiple scripts to be run  in  order.  Combine
              with -n to disable loading of the default script default.pa (see

       -C     Open a command interpreter on STDIN/STDOUT after  startup.  This
              may  be used to configure PulseAudio dynamically during runtime.
              Equivalent to --load=module-cli.

       -n     Don't  load  default  script  file  default.pa  (see  below)  on
              startup. Useful in conjunction with -C or --file.

       ~/.config/pulse/daemon.conf, /etc/pulse/daemon.conf: configuration set-
       tings for the PulseAudio daemon. If the  version  in  the  user's  home
       directory  does  not exist the global configuration file is loaded. See
       pulse-daemon.conf(5) for more information.

       ~/.config/pulse/default.pa, /etc/pulse/default.pa: the default configu-
       ration  script to execute when the PulseAudio daemon is started. If the
       version in the user's home directory does not exist the global configu-
       ration script is loaded. See default.pa(5) for more information.

       ~/.config/pulse/client.conf, /etc/pulse/client.conf: configuration set-
       tings for PulseAudio client applications. If the version in the  user's
       home  directory does not exist the global configuration file is loaded.
       See pulse-client.conf(5) for more information.

       SIGINT, SIGTERM: the PulseAudio daemon will shut down (Same as --kill).

       SIGHUP: dump a long status report to STDOUT or syslog, depending on the

       SIGUSR1:   load   module-cli,   allowing  runtime  reconfiguration  via

       SIGUSR2: load module-cli-protocol-unix, allowing  runtime  reconfigura-
       tion via a AF_UNIX socket. See pacmd(1) for more information.

       Group  pulse-access:  if  PulseAudio is running as a system daemon (see
       --system above) access is granted to members of this  group  when  they
       connect  via AF_UNIX sockets. If PulseAudio is running as a user daemon
       this group has no meaning.

       User pulse, group pulse: if PulseAudio is running as  a  system  daemon
       (see --system above) and is started as root the daemon will drop privi-
       leges and become a normal user process using this user  and  group.  If
       PulseAudio is running as a user daemon this user and group has no mean-

       To minimize the risk of drop-outs during playback it is recommended  to
       run  PulseAudio  with  real-time  scheduling if the underlying platform
       supports it. This decouples the scheduling latency  of  the  PulseAudio
       daemon  from the system load and is thus the best way to make sure that
       PulseAudio always gets CPU time when it needs it to refill the hardware
       playback  buffers.  Unfortunately  this  can be a security risk on some
       systems, since PulseAudio runs as user  process,  and  giving  realtime
       scheduling  privileges  to  a  user always comes with the risk that the
       user misuses it to lock up the system -- which is possible since making
       a  process  real-time  effectively  disables  preemption. To solve this
       problem, PulseAudio uses rtkit to safely acquire  real-time  scheduling
       when available.

       If  the  risk of locking up the machine is considered too big to enable
       real-time scheduling, high-priority scheduling can be  enabled  instead
       (i.e.  negative nice level). This can be enabled by passing --high-pri-
       ority (see above) when starting PulseAudio and may also be enabled with
       the appropriate option in daemon.conf. Negative nice levels can only be
       enabled when the appropriate resource limit  RLIMIT_NICE  is  set  (see
       setrlimit(2)  for  more information), possibly configured in /etc/secu-
       rity/limits.conf. A resource limit of 31 (corresponding with nice level
       -11) is recommended.

       The  PulseAudio client libraries check for the existence of the follow-
       ing environment variables and change their local configuration  accord-

       $PULSE_SERVER:  the  server  string specifying the server to connect to
       when a client asks for a sound server connection and doesn't explicitly
       ask  for  a  specific  server.  The  server  string is a list of server
       addresses separated by whitespace which are tried  in  turn.  A  server
       address  consists  of  an optional address type specifier (unix:, tcp:,
       tcp4:, tcp6:), followed by a path or host address. A host  address  may
       include  an optional port number. A server address may be prefixed by a
       string enclosed in {}. In this case the  following  server  address  is
       ignored  unless  the  prefix  string  equals  the local hostname or the
       machine id (/etc/machine-id).

       $PULSE_SINK: the symbolic name of the sink to connect to when a  client
       creates  a  playback  stream  and doesn't explicitly ask for a specific

       $PULSE_SOURCE: the symbolic name of the source to  connect  to  when  a
       client  creates  a  record stream and doesn't explicitly ask for a spe-
       cific source.

       $PULSE_BINARY: path of PulseAudio executable to run when  server  auto-
       spawning is used.

       $PULSE_CLIENTCONFIG:  path  of  file  that  shall  be  read  instead of
       client.conf (see above) for client configuration.

       $PULSE_COOKIE: path of file that contains the PulseAudio authentication
       cookie. Defaults to ~/.config/pulse/cookie.

       These  environment  settings take precedence -- if set -- over the con-
       figuration settings from client.conf (see above).

       The  PulseAudio  Developers  <pulseaudio-discuss   (at)   lists   (dot)
       freedesktop  (dot)  org>;  PulseAudio is available from http://pulseau-

       See attributes(7) for descriptions of the following attributes:

       |Availability   | library/audio/pulseaudio |
       |Stability      | Pass-through volatile    |

       pulse-daemon.conf(5), default.pa(5), pulse-client.conf(5), pacmd(1)

       Source code for open source software components in Oracle  Solaris  can
       be found at https://www.oracle.com/downloads/opensource/solaris-source-

       This    software    was    built    from    source     available     at
       https://github.com/oracle/solaris-userland.    The  original  community
       source was  downloaded  from   http://freedesktop.org/software/pulseau-

       Further information about this software can be found on the open source
       community website at http://freedesktop.org/software/pulseaudio.

Manuals                              User                        pulseaudio(1)