Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
pulseaudio(1)		    General Commands Manual		 pulseaudio(1)

NAME
       pulseaudio - The	PulseAudio Sound System

SYNOPSIS
       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

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

OPTIONS
       -h | --help
	      Show help.

       --version
	      Show version information.

       --dump-conf
	      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.

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

       --dump-resample-methods
	      List available audio resamplers.

       --cleanup-shm
	      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
	      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).

       --check
	      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  ex-
	      ample, 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.

       --system[=BOOL]
	      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[=BOOL]
	      Fail startup when	any of the commands specified in  the  startup
	      script default.pa	(see below) fails.

       --high-priority[=BOOL]
	      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).

       --realtime[=BOOL]
	      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[=BOOL]
	      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-exit[=BOOL]
	      Disallow user requested exit

       --exit-idle-time=SECS
	      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  al-
	      ways disabled, so	this option does nothing.

       --scache-idle-time=SECS
	      Unload  autoloaded samples from the cache	when they haven't been
	      used for the specified number of seconds.

       --log-level[=LEVEL]
	      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  er-
	      ror,  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
	      times.

       --log-target={auto,syslog,journal,stderr,file:PATH,newfile:PATH}
	      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.

       --log-meta[=BOOL]
	      Show source code location	in log messages.

       --log-time[=BOOL]
	      Show timestamps in log messages.

       --log-backtrace=FRAMES
	      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).

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

       --use-pid-file[=BOOL]
	      Create a PID file. If this options is disabled it	is possible to
	      run multiple sound servers per user.

       --no-cpu-limit[=BOOL]
	      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-
	      tion.

       --disable-shm[=BOOL]
	      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).

       --enable-memfd[=BOOL]
	      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
	      below).

       -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.

FILES
       ~/.config/pulse/daemon.conf, /usr/local/etc/pulse/daemon.conf: configu-
       ration settings 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,  /usr/local/etc/pulse/default.pa:  the  de-
       fault  configuration  script  to	 execute when the PulseAudio daemon is
       started.	If the version in the user's home directory does not exist the
       global  configuration  script is	loaded.	See default.pa(5) for more in-
       formation.

       ~/.config/pulse/client.conf, /usr/local/etc/pulse/client.conf: configu-
       ration  settings	 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.

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

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

       SIGUSR1:	 load  module-cli,  allowing   runtime	 reconfiguration   via
       STDIN/STDOUT.

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

UNIX GROUPS AND	USERS
       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-
       ing.

REAL-TIME AND HIGH-PRIORITY SCHEDULING
       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.

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

       $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  ad-
       dresses	separated  by whitespace which are tried in turn. A server ad-
       dress 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 ig-
       nored 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
       sink.

       $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).

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

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

Manuals				     User			 pulseaudio(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | FILES | SIGNALS | UNIX GROUPS AND USERS | REAL-TIME AND HIGH-PRIORITY SCHEDULING | ENVIRONMENT VARIABLES | AUTHORS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=pulseaudio&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help