Documentation updates

git-svn-id: file:///home/lennart/svn/public/pulseaudio/trunk@310 fefdeb5f-60dc-0310-8127-8f9354f1896f
2025-10-29 05:40:23 -04:00 · 2004-11-21 22:07:47 +00:00 · 2004-11-21 22:07:47 +00:00 · 9f23c8f362
commit 9f23c8f362
parent 4763ca1376
7 changed files with 96 additions and 44 deletions
--- a/doc/FAQ.html.in
+++ b/doc/FAQ.html.in
@ -126,9 +126,11 @@ connect to a running polypaudio daemon try using the following commands:</p>
 <pre>killall -USR2 polypaudio
 bidilink unix-client:/tmp/polypaudio/cli</pre>

-<p><i>BTW: Someone should package that great tool for Debian!</i></p></li>
+<p><i>BTW: Someone should package that great tool for Debian!</i></p>


+<p><b>New:</b> There's now a tool <tt>pacmd</tt> that automates sending SIGUSR2 to the daemon and running a bidilink like tool for you.</p>
+</li>

 <li><p><b>How do the polypaudio libraries decide where to connect to?</b></p>
 <p>The following rule applies:</p>
@ -142,10 +144,11 @@ bidilink unix-client:/tmp/polypaudio/cli</pre>
  <li>If <tt>$DISPLAY</tt> is set, the library tries to connect to the default TCP port of that host. If the connection fails, it proceeds with the next item.</li>
  <li>The connection fails.</li>
 </ol>
-<p></p>
-
 </li>

+<li><p><b>Why the heck does libpolyp link against libX11?</b></p>
+<p>The Polypaudio client libraries look for some X11 root window properties for the credentials of the Polypaudio server to access. You may compile Polypaudio without X11 for disabling this.</p></li>
+
 </ol>

 <hr/>
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@ -30,11 +30,11 @@ CLEANFILES += README
 endif

 tidy: README.html cli.html modules.html daemon.html
-	tidy -e < README.html
-	tidy -e < cli.html
-	tidy -e < daemon.html
-	tidy -e < modules.html
-	tidy -e < FAQ.html
+	tidy -qe < README.html
+	tidy -qe < cli.html
+	tidy -qe < daemon.html
+	tidy -qe < modules.html
+	tidy -qe < FAQ.html

 .PHONY: tidy

--- a/doc/README.html.in
+++ b/doc/README.html.in
@ -44,15 +44,8 @@ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.</p>

 <div class="news-date">Sun Nov 21 2004: </div> <p class="news-text"><a
 href="@PACKAGE_URL@polypaudio-0.7.tar.gz">Version 0.7</a> released;
-changes include: TCP wrappers support; don't load the complete sound
-file into memory when playing back using <tt>pa_play_file()</tt>;
-autoload API change; don't load all sound files as FLOAT32; shorten
-default buffers; client-side latency interpolation; add new user
-volume metrics; add <tt>module-tunnel</tt>, <tt>module-null-sink</tt>,
-<tt>module-match</tt> and new tool <tt>paplay</tt>; new API version
-macros; many client API improvements; correctly lock cookie file
-generation; correctly lock daemon autospawning; print daemon layout to
-STDERR on SIGHUP; new options for <tt>pacat</tt>: allow sample type specification.</p>
+changes include: IPv6 support; PID file support; publish credentials
+in X11 root window (<tt>module-x11-publish</tt>; new tool <tt>pacmd</tt>; ESOUND backend; new command <tt>load-sample-dir-lazy</tt>; many, many minor fixes.</p>

 <div class="news-date">Thu Oct 28 2004: </div> <p class="news-text"><a
 href="@PACKAGE_URL@polypaudio-0.6.tar.gz">Version 0.6</a> released;
@ -103,8 +96,9 @@ href="@PACKAGE_URL@polypaudio-0.1.tar.gz">Version 0.1</a> released</p>
 operating systems. It is intended to be an improved drop-in
 replacement for the <a
 href="http://www.tux.org/~ricdude/apps.html">Enlightened Sound
-Daemon</a> (ESOUND). In addition to the features ESOUND provides
-<tt>polypaudio</tt> has:</p>
+Daemon</a> (ESOUND). It is my ultimate ambition to get Polypaudio into
+<a href="http://www.gnome.org/">Gnome</a> as a replacement for ESOUND. In
+addition to the features ESOUND provides <tt>polypaudio</tt> has:</p>

 <ul>
  <li>Extensible plugin architecture (by loading dynamic loadable modules with <tt>dlopen()</tt>)</li>
@ -139,13 +133,15 @@ available. A simple main loop implementation is available as well.</p>
  <li><tt>module-combine</tt>: combine multiple sinks into one.</li>
  <li><tt>module-sine</tt>: a sine generate sink input.</li>
  <li><tt>module-x11-bell</tt>: play a sample from the sample cache on every X11 bell event.</li>
-  <li><tt>module-esound-protocol-tcp</tt>, <tt>module-esound-protocol-unix</tt>: ESOUND compatibility modules (for TCP/IP resp. UNIX domain sockets)</li>
-  <li><tt>module-native-protocol-tcp</tt>, <tt>module-native-protocol-unix</tt>: Native polypaudio protocol (for TCP/IP resp. UNIX domain sockets)</li>
-  <li><tt>module-simple-protocol-tcp</tt>, <tt>module-simple-protocol-unix</tt>: Simplistic protocol for playback/capture for usage with tools like <tt>netcat</tt> (for TCP/IP resp. UNIX domain sockets)</li>
-  <li><tt>module-cli-protocol-tcp</tt>, <tt>module-cli-protocol-unix</tt>, <tt>module-cli</tt>: Expose polypaudio's internals whith a simple command line interface. (for TCP/IP resp. UNIX domain sockets resp. STDIN/STDOUT)</li>
+  <li><tt>module-x11-publish</tt>: store Polypaudio credentials in the X11 root window.</li>
+  <li><tt>module-esound-protocol-tcp</tt>, <tt>module-esound-protocol-tcp6</tt>, <tt>module-esound-protocol-unix</tt>: ESOUND compatibility modules (for TCP/IPv6 resp. TCP/IPv6 resp. UNIX domain sockets)</li>
+  <li><tt>module-native-protocol-tcp</tt>, <tt>module-native-protocol-tcp6</tt>, <tt>module-native-protocol-unix</tt>: Native polypaudio protocol (for TCP/IPv4 resp. TCP/IPv6 resp. UNIX domain sockets)</li>
+  <li><tt>module-simple-protocol-tcp</tt>, <tt>module-simple-protocol-tcp6</tt>, <tt>module-simple-protocol-unix</tt>: Simplistic protocol for playback/capture for usage with tools like <tt>netcat</tt> (for TCP/IP resp. UNIX domain sockets)</li>
+  <li><tt>module-cli-protocol-tcp</tt>, <tt>module-cli-protocol-tcp6</tt>, <tt>module-cli-protocol-unix</tt>, <tt>module-cli</tt>: Expose polypaudio's internals whith a simple command line interface. (for TCP/IP resp. UNIX domain sockets resp. STDIN/STDOUT)</li>
  <li><tt>module-tunnel-sink</tt>, <tt>module-tunnel-source</tt>: make sinks/sources from other hosts available locally.</li>
  <li><tt>module-match</tt>: adjust volume automatically for newly created playback streams based on a regular expression matching table.</li>
  <li><tt>module-null-sink</tt>: a clocked sink similar to <tt>/dev/null</tt>.</li>
+  <li><tt>module-esound-sink</tt>: a sink for forwarding audio data to an ESOUND server.</li>
 </ul>

 <p><tt>polypaudio</tt> is the successor of my previous, ill-fated
@ -156,10 +152,18 @@ href="http://asd.sf.net/">asd</a>.</p>
 href="http://0pointer.de/lennart/projects/paman/">Polypaudio
 Manager</a>. Another GTK GUI tool for Polypaudio is the <a
 href="http://0pointer.de/lennart/projects/pavumeter">Polypaudio Volume
-Meter</a>. There are output plugins for <a
+Meter</a>.</p>
+
+<p>There are output plugins for <a
 href="http://0pointer.de/lennart/projects/xmms-polyp/">XMMS</a>, <a
-href="http://0pointer.de/lennart/projects/libao-polyp/">libao</a> and <a href="http://0pointer.de/lennart/projects/gst-polyp/">gstreamer</a>. Drivers
-for <a href="http://mplayerhq.hu">MPlayer</a> and <a href="http://www.portaudio.com/">PortAudio</a> will be released shortly.</p>
+href="http://0pointer.de/lennart/projects/libao-polyp/">libao</a>
+(merged in <tt>libao</tt> SVN) and <a
+href="http://0pointer.de/lennart/projects/gst-polyp/">gstreamer</a>
+(merged in <tt>gstreamer-plugins</tt> CVS), <a
+href="http://mplayerhq.hu">MPlayer</a> (merged in MPlayer CVS) and <a
+href="http://xine.sf.net/">Xine</a> (merged in Xine CVS). Drivers for
+<a href="http://www.portaudio.com/">PortAudio</a> will be released
+shortly.</p>

 <h2><a name="status">Status</a></h2>

@ -227,10 +231,10 @@ questions.</p>

 <h2><a name="requirements">Requirements</a></h2>

-<p>Currently, <tt>polypaudio</tt> is tested on Linux only. It requires an OSS or ALSA compatible soundcard.</p>
+<p>Currently, <tt>polypaudio</tt> is tested on Linux and FreeBSD only. It requires an OSS or ALSA compatible soundcard.</p>

 <p><tt>polypaudio</tt> was developed and tested on Debian GNU/Linux
-"testing" from July 2004, it should work on most other Linux
+"testing" from November 2004, it should work on most other Linux
 distributions (and maybe Unix versions) since it uses GNU autoconf and
 GNU libtool for source code configuration and shared library
 management.</p>
@ -255,6 +259,12 @@ compilation and <tt>make install</tt> (as root) for installation of

 <p>Eric B. Mitchell for writing ESOUND</p>

+<p>Jeff Waugh for creating Ubuntu packages (and hopefully soon Debian)</p>
+
+<p>Miguel Freitas for writing a Polypaudio driver for Xine</p>
+
+<p>Joe Marcus Clarke for porting Polypaudio to FreeBSD</p>
+
 <h2><a name="download">Download</a></h2>

 <p>The newest release is always available from <a href="@PACKAGE_URL@">@PACKAGE_URL@</a></p>
@ -272,7 +282,7 @@ compilation and <tt>make install</tt> (as root) for installation of
 <p><b>New!</b> There is now a <a href="http://0pointer.de/trac/polypaudio/">Polypaudio wiki</a> (based on <a href="http://www.edgewall.com/products/trac/">trac</a>) available.</p>

 <hr/>
-<address class="grey">Lennart Poettering &lt;@PACKAGE_BUGREPORT@&gt;, October 2004</address>
+<address class="grey">Lennart Poettering &lt;@PACKAGE_BUGREPORT@&gt;, November 2004</address>
 <div class="grey"><i>$Id$</i></div>

 </body>
--- a/doc/cli.html.in
+++ b/doc/cli.html.in
@ -112,6 +112,12 @@ immediately. The sample is loaded only when it is first used. After a
 certain idle time it is freed again. Expects the the desired sample
 name and file name to load as arguments.</p>

+<h3><tt>load-sample-dir-lazy</tt></h3>
+
+<p>Load all entries in the specified directory into the sample cache
+as lazy entries. A shell globbing expression (e.g. <tt>*.wav</tt>) may
+be appended to the path of the directory to add.</p>
+
 <h2>Module Autoloading</h2>

 <h3><tt>list-autoload</tt></h3>
@ -203,6 +209,6 @@ play-file /usr/share/sounds/startup3.wav combined
 </pre>

 <hr/>
-<address class="grey">Lennart Poettering &lt;@PACKAGE_BUGREPORT@&gt;, September 2004</address>
+<address class="grey">Lennart Poettering &lt;@PACKAGE_BUGREPORT@&gt;, November 2004</address>
 <div class="grey"><i>$Id$</i></div>
 </body> </html>
--- a/doc/daemon.html.in
+++ b/doc/daemon.html.in
@ -14,26 +14,42 @@
 The <tt>polypaudio</tt> daemon accepts several command line arguments:

 <pre>
+COMMANDS:
  -h, --help                            Show this help
      --version                         Show version
      --dump-conf                       Dump default configuration
      --dump-modules                    Dump list of available modules
+  -k  --kill                            Kill a running daemon
+      --check                           Check for a running daemon

+OPTIONS:
  -D, --daemonize[=BOOL]                Daemonize after startup
      --fail[=BOOL]                     Quit when startup fails
      --verbose[=BOOL]                  Be slightly more verbose
-      --high-priority[=BOOL]            Try to set high process priority (only available as root)
+      --high-priority[=BOOL]            Try to set high process priority
+                                        (only available as root)
      --disallow-module-loading[=BOOL]  Disallow module loading after startup
-      --exit-idle-time=SECS             Terminate the daemon when idle and this time passed
-      --module-idle-time=SECS           Unload autoloaded modules when idle and this time passed
-      --scache-idle-time=SECS           Unload autoloaded samples when idle and this time passed
+      --exit-idle-time=SECS             Terminate the daemon when idle and this
+                                        time passed
+      --module-idle-time=SECS           Unload autoloaded modules when idle and
+                                        this time passed
+      --scache-idle-time=SECS           Unload autoloaded samples when idle and
+                                        this time passed
      --log-target={auto,syslog,stderr} Specify the log target
-  -p, --dl-search-path=PATH             Set the search path for dynamic shared objects (plugins)
+  -p, --dl-search-path=PATH             Set the search path for dynamic shared
+                                        objects (plugins)
      --resample-method=[METHOD]        Use the specified resampling method
+                                        (one of src-sinc-medium-quality,
+                                        src-sinc-best-quality,src-sinc-fastest
+                                        src-zero-order-hold,src-linear,trivial)
+      --use-pid-file[=BOOL]             Create a PID file

-  -L, --load="MODULE ARGUMENTS"         Load the specified plugin module with the specified argument
+STARTUP SCRIPT:
+  -L, --load="MODULE ARGUMENTS"         Load the specified plugin module with
+                                        the specified argument
  -F, --file=FILENAME                   Run the specified script
-  -C                                    Open a command line on the running TTY after startup (identical to -Lmodule-cli)
+  -C                                    Open a command line on the running TTY
+                                        after startup

  -n                                    Don't load default script file
 </pre>
@ -67,6 +83,6 @@ The <tt>polypaudio</tt> daemon accepts several command line arguments:
 <p>The daemon logs the current server layout.</p>

 <hr/>
-<address class="grey">Lennart Poettering &lt;@PACKAGE_BUGREPORT@&gt;, September 2004</address>
+<address class="grey">Lennart Poettering &lt;@PACKAGE_BUGREPORT@&gt;, November 2004</address>
 <div class="grey"><i>$Id$</i></div>
 </body> </html>
--- a/doc/modules.html.in
+++ b/doc/modules.html.in
@ -267,6 +267,26 @@ about the two possible suffixes of this module.</p>
  <tr><td><tt>sink=</tt></td><td>Name of the sink to play the sample on. If ommited defaults to the default sink.</td></tr>
 </table>

+<h3>module-x11-publish</h3>
+
+<p>Publishes the access credentials to the Polypaudio server in the
+X11 root window. The following properties are used:
+<tt>POLYP_SERVER</tt>, <tt>POYLP_SINK</tt>, <tt>POLYP_SOURCE</tt>,
+<tt>POLYP_COOKIE</tt>. This is very useful when using SSH or any other
+remote login tool for logging into other machines and getting audio
+playback to your local speakers. The Polypaudio client libraries make
+use of this data automatically. Instead of using this module you may
+use the tool <tt>pax11publish</tt> which may be used to access, modify
+and import credential data from/to the X11 display.</p>
+
+<table>
+  <tr><td><tt>display=</tt></td><td>X11 display to connect to. If ommited defaults to the value of <tt>$DISPLAY</tt></td></tr>
+  <tr><td><tt>sink=</tt></td><td>Name of the default sink. If ommited this property isn't stored in the X11 display.</td></tr>
+  <tr><td><tt>source=</tt></td><td>Name of the default source. If ommited this property isn't stored in the X11 display.</td></tr>
+  <tr><td><tt>cookie=</tt></td><td>Name of the cookie file of the
+cookie to store in the X11 display. If ommited the cookie of an
+already loaded protocol module is used.</td></tr> </table>
+
 <h3>module-sine</h3>

 <p>Creates a sink input and generates a sine waveform stream.</p>
@ -301,6 +321,6 @@ about the two possible suffixes of this module.</p>
 <p>The volumes of all streams with titles starting with <tt>sample:</tt> are automatically set to 25. (FYI: All sample cache streams start with <tt>sample:</tt>)</p>

 <hr/>
-<address class="grey">Lennart Poettering &lt;@PACKAGE_BUGREPORT@&gt;, September 2004</address>
+<address class="grey">Lennart Poettering &lt;@PACKAGE_BUGREPORT@&gt;, November 2004</address>
 <div class="grey"><i>$Id$</i></div>
 </body> </html>
--- a/doc/todo
+++ b/doc/todo
@ -1,10 +1,7 @@
 *** $Id$ ***

-*** 0.7 ****
- limit all resources
- commenting
-
-** later ***
+*** later ****
+- event more commenting
 - polish for starting polypaudio as root/system-wide instance
 - per-channel volume
 - improve module-oss-mmap latency measurement