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)

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

home | help