From 7fdc1ee0838d3c55e29d8f44f2919a60f9415e56 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Mon, 5 Nov 2007 23:56:00 +0000 Subject: add a couple of more man pages git-svn-id: file:///home/lennart/svn/public/pulseaudio/trunk@2024 fefdeb5f-60dc-0310-8127-8f9354f1896f --- man/Makefile.am | 72 ++++++++++++++++++++- man/esdcompat.1.xml.in | 91 ++++++++++++++++++++++++++ man/pacat.1.xml.in | 160 ++++++++++++++++++++++++++++++++++++++++++++++ man/pacmd.1.xml.in | 52 +++++++++++++++ man/pactl.1.xml.in | 145 +++++++++++++++++++++++++++++++++++++++++ man/paplay.1.xml.in | 129 +++++++++++++++++++++++++++++++++++++ man/pax11publish.1.xml.in | 153 ++++++++++++++++++++++++++++++++++++++++++++ man/pulseaudio.1.xml.in | 69 +++++++++++++++++++- 8 files changed, 867 insertions(+), 4 deletions(-) create mode 100644 man/esdcompat.1.xml.in create mode 100644 man/pacat.1.xml.in create mode 100644 man/pacmd.1.xml.in create mode 100644 man/pactl.1.xml.in create mode 100644 man/paplay.1.xml.in create mode 100644 man/pax11publish.1.xml.in (limited to 'man') diff --git a/man/Makefile.am b/man/Makefile.am index b701a2ea..a3427aa7 100644 --- a/man/Makefile.am +++ b/man/Makefile.am @@ -22,10 +22,22 @@ pulseconfdir=$(sysconfdir)/pulse if BUILD_MANPAGES man_MANS = \ - pulseaudio.1 + pulseaudio.1 \ + esdcompat.1 \ + pax11publish.1 \ + paplay.1 \ + pacat.1 \ + pacmd.1 \ + pactl.1 noinst_DATA = \ - pulseaudio.1.xml + pulseaudio.1.xml \ + esdcompat.1.xml \ + pax11publish.1.xml \ + paplay.1.xml \ + pacat.1.xml \ + pacmd.1.xml \ + pactl.1.xml CLEANFILES = \ $(noinst_DATA) @@ -35,6 +47,36 @@ pulseaudio.1.xml: pulseaudio.1.xml.in Makefile -e 's,@PACKAGE_BUGREPORT\@,$(PACKAGE_BUGREPORT),g' \ -e 's,@PACKAGE_URL\@,$(PACKAGE_URL),g' $< > $@ +esdcompat.1.xml: esdcompat.1.xml.in Makefile + sed -e 's,@pulseconfdir\@,$(pulseconfdir),g' \ + -e 's,@PACKAGE_BUGREPORT\@,$(PACKAGE_BUGREPORT),g' \ + -e 's,@PACKAGE_URL\@,$(PACKAGE_URL),g' $< > $@ + +pax11publish.1.xml: pax11publish.1.xml.in Makefile + sed -e 's,@pulseconfdir\@,$(pulseconfdir),g' \ + -e 's,@PACKAGE_BUGREPORT\@,$(PACKAGE_BUGREPORT),g' \ + -e 's,@PACKAGE_URL\@,$(PACKAGE_URL),g' $< > $@ + +paplay.1.xml: paplay.1.xml.in Makefile + sed -e 's,@pulseconfdir\@,$(pulseconfdir),g' \ + -e 's,@PACKAGE_BUGREPORT\@,$(PACKAGE_BUGREPORT),g' \ + -e 's,@PACKAGE_URL\@,$(PACKAGE_URL),g' $< > $@ + +pacat.1.xml: pacat.1.xml.in Makefile + sed -e 's,@pulseconfdir\@,$(pulseconfdir),g' \ + -e 's,@PACKAGE_BUGREPORT\@,$(PACKAGE_BUGREPORT),g' \ + -e 's,@PACKAGE_URL\@,$(PACKAGE_URL),g' $< > $@ + +pacmd.1.xml: pacmd.1.xml.in Makefile + sed -e 's,@pulseconfdir\@,$(pulseconfdir),g' \ + -e 's,@PACKAGE_BUGREPORT\@,$(PACKAGE_BUGREPORT),g' \ + -e 's,@PACKAGE_URL\@,$(PACKAGE_URL),g' $< > $@ + +pactl.1.xml: pactl.1.xml.in Makefile + sed -e 's,@pulseconfdir\@,$(pulseconfdir),g' \ + -e 's,@PACKAGE_BUGREPORT\@,$(PACKAGE_BUGREPORT),g' \ + -e 's,@PACKAGE_URL\@,$(PACKAGE_URL),g' $< > $@ + if USE_XMLTOMAN CLEANFILES += \ @@ -43,6 +85,24 @@ CLEANFILES += \ pulseaudio.1: pulseaudio.1.xml Makefile xmltoman $< > $@ +esdcompat.1: esdcompat.1.xml Makefile + xmltoman $< > $@ + +pax11publish.1: pax11publish.1.xml Makefile + xmltoman $< > $@ + +paplay.1: paplay.1.xml Makefile + xmltoman $< > $@ + +pacat.1: pacat.1.xml Makefile + xmltoman $< > $@ + +pacmd.1: pacmd.1.xml Makefile + xmltoman $< > $@ + +pactl.1: pactl.1.xml Makefile + xmltoman $< > $@ + xmllint: $(noinst_DATA) for f in $(noinst_DATA) ; do \ xmllint --noout --valid "$$f" || exit 1 ; \ @@ -54,7 +114,13 @@ endif EXTRA_DIST = \ $(man_MANS) \ - pulseaudio.1.xml.in + pulseaudio.1.xml.in \ + esdcompat.1.xml.in \ + pax11publish.1.xml.in \ + paplay.1.xml.in \ + pacat.1.xml.in \ + pacmd.1.xml.in \ + pactl.1.xml.in \ xmltoman.css \ xmltoman.xsl \ xmltoman.dtd diff --git a/man/esdcompat.1.xml.in b/man/esdcompat.1.xml.in new file mode 100644 index 00000000..864dc5db --- /dev/null +++ b/man/esdcompat.1.xml.in @@ -0,0 +1,91 @@ + + + + + + + + + + + + esdcompat [options] + esdcompat --help + esdcompat --version + + + +

esdcompat is a compatiblity script that takes the + same arguments as the ESD sound daemon , but uses them to start a the PulseAudio sound server with the appropriate parameters. It is + required to make PulseAudio a drop-in replacement for esd, i.e. it + can be used to make + start up PulseAudio instead of esd.

+ +

It is recommended to make esd a symbolic link to this script.

+ + + + + + + + + + + + + + + +
+

The PulseAudio Developers <@PACKAGE_BUGREPORT@>; PulseAudio is available from

+
+ +
+

+ , +

+
+ + diff --git a/man/pacat.1.xml.in b/man/pacat.1.xml.in new file mode 100644 index 00000000..35c7651b --- /dev/null +++ b/man/pacat.1.xml.in @@ -0,0 +1,160 @@ + + + + + + + + + + + + pacat [options] [FILE] + parec [options] [FILE] + paplay --help + paplay --version + + + +

pacat is a simple tool for playing back or + capturing raw audio files on a PulseAudio sound server.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+

The PulseAudio Developers <@PACKAGE_BUGREPORT@>; PulseAudio is available from

+
+ +
+

+ , +

+
+ + diff --git a/man/pacmd.1.xml.in b/man/pacmd.1.xml.in new file mode 100644 index 00000000..b760ba0e --- /dev/null +++ b/man/pacmd.1.xml.in @@ -0,0 +1,52 @@ + + + + + + + + + + + + pacmd + + + +

This tool can be used to introspect or reconfigure a running + PulseAudio sound server during runtime. It connects to the sound + server and offers a simple live shell that can be used to enter + the commands also understood in the default.pa + configuration scripts.

+ +

This program takes no command line options.

+ + +
+

The PulseAudio Developers <@PACKAGE_BUGREPORT@>; PulseAudio is available from

+
+ +
+

+ , , +

+
+ + diff --git a/man/pactl.1.xml.in b/man/pactl.1.xml.in new file mode 100644 index 00000000..0b7b9a78 --- /dev/null +++ b/man/pactl.1.xml.in @@ -0,0 +1,145 @@ + + + + + + + + + + + + pulseaudio [options] stat + pulseaudio [options] list + pulseaudio [options] exit + pulseaudio [options] upload-sample FILENAME [NAME] + pulseaudio [options] play-sample NAME [SINK] + pulseaudio [options] remove-sample NAME + pulseaudio [options] move-sink-input ID SINK + pulseaudio [options] move-source-input ID SOURCE + pulseaudio [options] load-module NAME [ARGUMENTS ...] + pulseaudio [options] unload-module ID + pulseaudio [options] suspend-sink [SINK] 1|0 + pulseaudio [options] suspend-source [SOURCE] 1|0 + pulseaudio --help + pulseaudio --version + + + +

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

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+

The PulseAudio Developers <@PACKAGE_BUGREPORT@>; PulseAudio is available from

+
+ +
+

+ , +

+
+ + diff --git a/man/paplay.1.xml.in b/man/paplay.1.xml.in new file mode 100644 index 00000000..bab45dc3 --- /dev/null +++ b/man/paplay.1.xml.in @@ -0,0 +1,129 @@ + + + + + + + + + + + + paplay [options] FILE + paplay --help + paplay --version + + + +

paplay is a simple tool for playing back audio + files on a PulseAudio sound server. It understands all audio file + formats supported by libsndfile.

+ + + + + + + + + + + + + + + + + + + + + + + + +
+ +

Due to a limitation in libsndfile + paplay currently does not always set the correct channel + mapping for playback of multichannel (i.e. surround) audio files, even if the channel mapping information is + available in the audio file.

+ +
+ +
+

The PulseAudio Developers <@PACKAGE_BUGREPORT@>; PulseAudio is available from

+
+ +
+

+ , +

+
+ + diff --git a/man/pax11publish.1.xml.in b/man/pax11publish.1.xml.in new file mode 100644 index 00000000..1e3a1f01 --- /dev/null +++ b/man/pax11publish.1.xml.in @@ -0,0 +1,153 @@ + + + + + + + + + + + + pax11publish -h + pax11publish [options] [-d] + pax11publish [options] -e + pax11publish [options] -i + pax11publish [options] -r + + + +

The pax11publish utility can be used to dump or + manipulate the PulseAudio server credentials that can be stored as + properties on the X11 root window.

+ +

Please note that the loadable module + module-x11-publish exports the same information + directly from the PulseAudio sound server, and should in most + cases be used in preference over this tool.

+ +

Use the following command to dump the raw + PulseAudio-specific data that is stored in your X11 root + window:

+ +

xprop -root | grep ^PULSE_

+ + + + + + + + + + + + + + + + + + + + + + + + + + + +
+

The PulseAudio Developers <@PACKAGE_BUGREPORT@>; PulseAudio is available from

+
+ +
+

+ , +

+
+ + diff --git a/man/pulseaudio.1.xml.in b/man/pulseaudio.1.xml.in index b30f4484..1f53a60b 100644 --- a/man/pulseaudio.1.xml.in +++ b/man/pulseaudio.1.xml.in @@ -28,6 +28,7 @@ USA. pulseaudio [options] pulseaudio --help + pulseaudio --version pulseaudio --dump-conf pulseaudio --dump-modules pulseaudio --dump-resample-methods @@ -363,7 +364,73 @@ USA.
- Blablub +

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 is a security risk on most systems, + since PulseAudio runs as user process, and giving realtime + scheduling priviliges to a user process 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 minimize the risk PulseAudio by default does not enable + real-time scheduling. It is however recommended to enable it + on trusted systems. To do that start PulseAudio with + --realtime (see above) or enabled the appropriate option in + daemon.conf. Since acquiring realtime scheduling is a + priviliged operation on most systems, some special changes to the + system configuration need to be made to allow them to the calling + user. Two options are available:

+ +

On newer Linux systems the system resource limit RLIMIT_RTPRIO + (see for more information) + can be used to allow specific users to acquire real-time + scheduling. This can be configured in + /etc/security/limits.conf, a resource limit of 9 is recommended.

+ +

Alternatively, the SUID root bit can be set for the PulseAudio + binary. Then, the daemon will drop root priviliges immediately on + startup, however retain the CAP_NICE capability (on systems that + support it), but only if the calling user is a member of the + pulse-rt group (see above). For all other users all + capababilities are dropped immediately. The advantage of this + solution is that the real-time priviliges are only granted to the + PulseAudio daemon -- not to all the user's processes.

+ +

Alternatively, 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-priority (see above) + when starting PulseAudio and may also be enabled with the + approriate option in daemon.conf. Negative nice + levels can only be enabled when the appropriate resource limit + RLIMIT_NICE is set (see for + more information), possibly configured in + /etc/security/limits.conf. A resource limit of 31 + (corresponding with nice level -11) is recommended.

+
+ +
+ +

The PulseAudio client libraries check for the existance of the + following environment variables and change their local configuration accordingly:

+ +

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

+ +

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

+ +

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

+
-- cgit