1pulseaudio(1)               General Commands Manual              pulseaudio(1)
2
3
4

NAME

6       pulseaudio - The PulseAudio Sound System
7

SYNOPSIS

9       pulseaudio [options]
10
11       pulseaudio --help
12
13       pulseaudio --version
14
15       pulseaudio --dump-conf
16
17       pulseaudio --dump-modules
18
19       pulseaudio --dump-resample-methods
20
21       pulseaudio --cleanup-shm
22
23       pulseaudio --start
24
25       pulseaudio --kill
26
27       pulseaudio --check
28

DESCRIPTION

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

OPTIONS

34       -h | --help
35              Show help.
36
37       --version
38              Show version information.
39
40       --dump-conf
41              Load the daemon  configuration  file  daemon.conf  (see  below),
42              parse  remaining  configuration  options on the command line and
43              dump the resulting daemon configuration, in  a  format  that  is
44              compatible with daemon.conf.
45
46       --dump-modules
47              List  available  loadable  modules.  Combine  with -v for a more
48              elaborate listing.
49
50       --dump-resample-methods
51              List available audio resamplers.
52
53       --cleanup-shm
54              Identify  stale  PulseAudio  POSIX  shared  memory  segments  in
55              /dev/shm  and  remove  them if possible. This is done implicitly
56              whenever a new daemon starts up or a client tries to connect  to
57              a daemon. It should normally not be necessary to issue this com‐
58              mand by hand. Only available on systems with POSIX shared memory
59              segments  implemented  via  a  virtual  file  system  mounted to
60              /dev/shm (e.g. Linux).
61
62       --start
63              Start PulseAudio if it is not running  yet.  This  is  different
64              from  starting PulseAudio without --start which would fail if PA
65              is already running. PulseAudio is guaranteed to  be  fully  ini‐
66              tialized when this call returns. Implies --daemonize.
67
68       -k | --kill
69              Kill  an  already  running PulseAudio daemon of the calling user
70              (Equivalent to sending a SIGTERM).
71
72       --check
73              Return 0 as return code when the PulseAudio  daemon  is  already
74              running for the calling user, or non-zero otherwise. Produces no
75              output on the console except for errors to stderr.
76
77              Note that a non-zero return value doesn't necessarily mean  that
78              PulseAudio  is not usable. Even if the server is not running, it
79              may get  automatically  started  via  PulseAudio's  autospawning
80              mechanism  or  systemd's  socket  activation, or the environment
81              might be such that checking  for  processes  doesn't  work  (for
82              example,  the  running  server might not show up in a container,
83              even if the server is accessible via a socket).  Also  disabling
84              PID files with --use-pid-file=no prevents --check from detecting
85              running servers.
86
87              A more robust check in most situations would be  to  try  estab‐
88              lishing a client connection to the server. Unfortunately there's
89              currently no --check-connection option to replace  --check,  but
90              running "pactl info" could be a pretty good substitute.
91
92       --system[=BOOL]
93              Run  as  system-wide  instance  instead of per-user. Please note
94              that this disables certain features of PulseAudio and is  gener‐
95              ally  not  recommended  unless  the  system knows no local users
96              (e.g. is a thin client). This feature needs  special  configura‐
97              tion  and a dedicated UNIX user set up. It is highly recommended
98              to combine this with --disallow-module-loading (see below).
99
100       -D | --daemonize[=BOOL]
101              Daemonize after startup, i.e. detach  from  the  terminal.  Note
102              that  when  running as a systemd service you should use --daemo‐
103              nize=no for systemd notification to work.
104
105       --fail[=BOOL]
106              Fail startup when any of the commands specified in  the  startup
107              script default.pa (see below) fails.
108
109       --high-priority[=BOOL]
110              Try to acquire a high Unix nice level. This will only succeed if
111              the calling user has a non-zero RLIMIT_NICE resource  limit  set
112              (on systems that support this), or we're configured to be run as
113              system daemon (see --system above). It is recommended to  enable
114              this, since it is only a negligible security risk (see below).
115
116       --realtime[=BOOL]
117              Try  to  acquire  a  real-time  scheduling  for PulseAudio's I/O
118              threads. This will only succeed if the calling user has  a  non-
119              zero  RLIMIT_RTPRIO  resource limit set (on systems that support
120              this), or rtkit is available and  allows  PulseAudio  to  enable
121              real-time  scheduling,  or we are configured to be run as system
122              daemon (see --system above).
123
124       --disallow-module-loading[=BOOL]
125              Disallow module loading after startup. This is a  security  fea‐
126              ture since it disallows additional module loading during runtime
127              and on user request. It is highly recommended when  --system  is
128              used  (see  above).  Note however, that this breaks certain fea‐
129              tures like automatic module loading on hot plug.
130
131       --disallow-exit[=BOOL]
132              Disallow user requested exit
133
134       --exit-idle-time=SECS
135              Terminate the daemon after the last client quit and this time in
136              seconds  passed.  Use  a negative value to disable this feature.
137              Defaults to 20.
138
139              When PulseAudio runs in the per-user mode and  detects  a  login
140              session,  then  any  positive  value  will be reset to 0 so that
141              PulseAudio will terminate  immediately  on  logout.  A  positive
142              value therefore has effect only in environments where there's no
143              support for login session tracking (or if the user is logged  in
144              without  a  session spawned, a.k.a. lingering). A negative value
145              can still be used to disable any automatic exit.
146
147              When PulseAudio runs in  the  system  mode,  automatic  exit  is
148              always disabled, so this option does nothing.
149
150       --scache-idle-time=SECS
151              Unload  autoloaded samples from the cache when they haven't been
152              used for the specified number of seconds.
153
154       --log-level[=LEVEL]
155              If an argument is passed, set the log  level  to  the  specified
156              value, otherwise increase the configured verbosity level by one.
157              The log levels are numerical  from  0  to  4,  corresponding  to
158              error,  warn,  notice, info, debug. Default log level is notice,
159              i.e. all log messages with lower log levels are printed:  error,
160              warn, notice.
161
162       -v | --verbose
163              Increase  the configured verbosity level by one (see --log-level
164              above). Specify multiple times to increase  log  level  multiple
165              times.
166
167       --log-target={auto,syslog,journal,stderr,file:PATH,newfile:PATH}
168              Specify  the  log target. If set to auto (which is the default),
169              then logging is directed to syslog when --daemonize  is  passed,
170              otherwise  to  STDERR.  If set to journal logging is directed to
171              the systemd journal. If set to file:PATH, logging is directed to
172              the  file  indicated by PATH. newfile:PATH is otherwise the same
173              as file:PATH, but existing files are never overwritten.  If  the
174              specified  file  already  exists,  a suffix is added to the file
175              name to avoid overwriting.
176
177       --log-meta[=BOOL]
178              Show source code location in log messages.
179
180       --log-time[=BOOL]
181              Show timestamps in log messages.
182
183       --log-backtrace=FRAMES
184              When FRAMES is greater than 0, log  for  each  message  a  stack
185              trace up to the number of specified stack frames.
186
187       -p | --dl-search-path=PATH
188              Set the search path for dynamic shared objects (plugins).
189
190       --resample-method=METHOD
191              Use  the  specified  resampler  by default (See --dump-resample-
192              methods above for possible values).
193
194       --use-pid-file[=BOOL]
195              Create a PID file. If this options is disabled it is possible to
196              run multiple sound servers per user.
197
198       --no-cpu-limit[=BOOL]
199              Do not install CPU load limiter on platforms that support it. By
200              default, PulseAudio will terminate itself when it  notices  that
201              it  takes  up  too much CPU time. This is useful as a protection
202              against system lockups when real-time scheduling  is  used  (see
203              below).  Disabling  this  mechanism  is  useful  when  debugging
204              PulseAudio with tools like valgrind(1) which  slow  down  execu‐
205              tion.
206
207       --disable-shm[=BOOL]
208              PulseAudio  clients  and  the server can exchange audio data via
209              POSIX or memfd shared memory segments (on systems  that  support
210              this).  If disabled PulseAudio will communicate exclusively over
211              sockets. Please note that data transfer via shared  memory  seg‐
212              ments  is always disabled when PulseAudio is running with --sys‐
213              tem enabled (see above).
214
215       --enable-memfd[=BOOL]
216              PulseAudio clients and the server can exchange  audio  data  via
217              memfds  - the anonymous Linux Kernel shared memory mechanism (on
218              kernels that support this). If disabled PulseAudio will communi‐
219              cate via POSIX shared memory.
220
221       -L | --load="MODULE ARGUMENTS"
222              Load the specified plugin module with the specified arguments.
223
224       -F | --file=FILENAME
225              Run  the  specified script on startup. May be specified multiple
226              times to specify multiple scripts to be run  in  order.  Combine
227              with -n to disable loading of the default script default.pa (see
228              below).
229
230       -C     Open a command interpreter on STDIN/STDOUT after  startup.  This
231              may  be used to configure PulseAudio dynamically during runtime.
232              Equivalent to --load=module-cli.
233
234       -n     Don't  load  default  script  file  default.pa  (see  below)  on
235              startup. Useful in conjunction with -C or --file.
236

FILES

238       ~/.config/pulse/daemon.conf, /etc/pulse/daemon.conf: configuration set‐
239       tings for the PulseAudio daemon. If the  version  in  the  user's  home
240       directory  does  not exist the global configuration file is loaded. See
241       pulse-daemon.conf(5) for more information.
242
243       ~/.config/pulse/default.pa, /etc/pulse/default.pa: the default configu‐
244       ration  script to execute when the PulseAudio daemon is started. If the
245       version in the user's home directory does not exist the global configu‐
246       ration script is loaded. See default.pa(5) for more information.
247
248       ~/.config/pulse/client.conf, /etc/pulse/client.conf: configuration set‐
249       tings for PulseAudio client applications. If the version in the  user's
250       home  directory does not exist the global configuration file is loaded.
251       See pulse-client.conf(5) for more information.
252

SIGNALS

254       SIGINT, SIGTERM: the PulseAudio daemon will shut down (Same as --kill).
255
256       SIGHUP: dump a long status report to STDOUT or syslog, depending on the
257       configuration.
258
259       SIGUSR1:   load   module-cli,   allowing  runtime  reconfiguration  via
260       STDIN/STDOUT.
261
262       SIGUSR2: load module-cli-protocol-unix, allowing  runtime  reconfigura‐
263       tion via a AF_UNIX socket. See pacmd(1) for more information.
264

UNIX GROUPS AND USERS

266       Group  pulse-access:  if  PulseAudio is running as a system daemon (see
267       --system above) access is granted to members of this  group  when  they
268       connect  via AF_UNIX sockets. If PulseAudio is running as a user daemon
269       this group has no meaning.
270
271       User pulse, group pulse: if PulseAudio is running as  a  system  daemon
272       (see --system above) and is started as root the daemon will drop privi‐
273       leges and become a normal user process using this user  and  group.  If
274       PulseAudio is running as a user daemon this user and group has no mean‐
275       ing.
276

REAL-TIME AND HIGH-PRIORITY SCHEDULING

278       To minimize the risk of drop-outs during playback it is recommended  to
279       run  PulseAudio  with  real-time  scheduling if the underlying platform
280       supports it. This decouples the scheduling latency  of  the  PulseAudio
281       daemon  from the system load and is thus the best way to make sure that
282       PulseAudio always gets CPU time when it needs it to refill the hardware
283       playback  buffers.  Unfortunately  this  can be a security risk on some
284       systems, since PulseAudio runs as user  process,  and  giving  realtime
285       scheduling  privileges  to  a  user always comes with the risk that the
286       user misuses it to lock up the system -- which is possible since making
287       a  process  real-time  effectively  disables  preemption. To solve this
288       problem, PulseAudio uses rtkit to safely acquire  real-time  scheduling
289       when available.
290
291       If  the  risk of locking up the machine is considered too big to enable
292       real-time scheduling, high-priority scheduling can be  enabled  instead
293       (i.e.  negative nice level). This can be enabled by passing --high-pri‐
294       ority (see above) when starting PulseAudio and may also be enabled with
295       the appropriate option in daemon.conf. Negative nice levels can only be
296       enabled when the appropriate resource limit  RLIMIT_NICE  is  set  (see
297       setrlimit(2)  for  more information), possibly configured in /etc/secu‐
298       rity/limits.conf. A resource limit of 31 (corresponding with nice level
299       -11) is recommended.
300

ENVIRONMENT VARIABLES

302       The  PulseAudio client libraries check for the existence of the follow‐
303       ing environment variables and change their local configuration  accord‐
304       ingly:
305
306       $PULSE_SERVER:  the  server  string specifying the server to connect to
307       when a client asks for a sound server connection and doesn't explicitly
308       ask  for  a  specific  server.  The  server  string is a list of server
309       addresses separated by whitespace which are tried  in  turn.  A  server
310       address  consists  of  an optional address type specifier (unix:, tcp:,
311       tcp4:, tcp6:), followed by a path or host address. A host  address  may
312       include  an optional port number. A server address may be prefixed by a
313       string enclosed in {}. In this case the  following  server  address  is
314       ignored  unless  the  prefix  string  equals  the local hostname or the
315       machine id (/etc/machine-id).
316
317       $PULSE_SINK: the symbolic name of the sink to connect to when a  client
318       creates  a  playback  stream  and doesn't explicitly ask for a specific
319       sink.
320
321       $PULSE_SOURCE: the symbolic name of the source to  connect  to  when  a
322       client  creates  a  record stream and doesn't explicitly ask for a spe‐
323       cific source.
324
325       $PULSE_BINARY: path of PulseAudio executable to run when  server  auto-
326       spawning is used.
327
328       $PULSE_CLIENTCONFIG:  path  of  file  that  shall  be  read  instead of
329       client.conf (see above) for client configuration.
330
331       $PULSE_COOKIE: path of file that contains the PulseAudio authentication
332       cookie. Defaults to ~/.config/pulse/cookie.
333
334       These  environment  settings take precedence -- if set -- over the con‐
335       figuration settings from client.conf (see above).
336

AUTHORS

338       The  PulseAudio  Developers  <pulseaudio-discuss   (at)   lists   (dot)
339       freedesktop  (dot)  org>;  PulseAudio is available from http://pulseau
340       dio.org/
341

SEE ALSO

343       pulse-daemon.conf(5), default.pa(5), pulse-client.conf(5), pacmd(1)
344
345
346
347Manuals                              User                        pulseaudio(1)
Impressum