documentation update

git-svn-id: file:///home/lennart/svn/public/pulseaudio/trunk@185 fefdeb5f-60dc-0310-8127-8f9354f1896f
author: Lennart Poettering <lennart@poettering.net> 2004-09-07 22:40:43 +0000
committer: Lennart Poettering <lennart@poettering.net> 2004-09-07 22:40:43 +0000
commit: 13248fd8e6cb44e489bd2d77d5ec3491287a1f4d (patch)
tree: 29d10ccf6edd075f80d85433fb2a921f52ed0633
parent: 70007175d28cf4c7323e772683bbe084e62df024 (diff)
11 files changed, 147 insertions, 23 deletions
diff --git a/configure.ac b/configure.ac
index f221689d4..d278ff8e4 100644
--- a/configure.ac
+++ b/configure.ac
@@ -20,7 +20,7 @@
 # Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
 
 AC_PREREQ(2.57)
-AC_INIT([polypaudio],[0.3],[mzcbylcnhqvb (at) 0pointer (dot) de])
+AC_INIT([polypaudio],[0.4],[mzcbylcnhqvb (at) 0pointer (dot) de])
 AC_CONFIG_SRCDIR([polyp/main.c])
 AC_CONFIG_HEADERS([config.h])
 AM_INIT_AUTOMAKE([foreign -Wall])
@@ -118,5 +118,5 @@ AM_CONDITIONAL([USE_LYNX], [test "x$lynx" = xyes])
 
 AM_CONDITIONAL(BUILD_LIBPOLYPCORE, false)
 
-AC_CONFIG_FILES([Makefile polyp/Makefile polyplib.pc polyplib-simple.pc polyplib-mainloop.pc polyplib-error.pc polyplib-glib-mainloop.pc polyplib-glib12-mainloop.pc doc/Makefile doc/README.html doc/cli.html doc/daemon.html doc/modules.html doxygen/Makefile doxygen/doxygen.conf polyp/polyplib-version.h])
+AC_CONFIG_FILES([Makefile polyp/Makefile polyplib.pc polyplib-simple.pc polyplib-mainloop.pc polyplib-error.pc polyplib-glib-mainloop.pc polyplib-glib12-mainloop.pc doc/Makefile doc/README.html doc/cli.html doc/daemon.html doc/modules.html doxygen/Makefile doxygen/doxygen.conf polyp/polyplib-version.h doc/FAQ.html])
 AC_OUTPUT
diff --git a/doc/FAQ.html.in b/doc/FAQ.html.in
new file mode 100644
index 000000000..074561c1f
--- /dev/null
+++ b/doc/FAQ.html.in
@@ -0,0 +1,77 @@
+<?xml version="1.0" encoding="iso-8859-1"?> <!-- -*-html-helper-*- -->
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>polypaudio: FAQ</title>
+<link rel="stylesheet" type="text/css" href="style.css" />
+</head>
+
+<body>
+
+
+<h1>Frequently Asked Questions</h1>
+
+<ol>
+  <li><p><b>How does Polypaudio compare with ESOUND/aRts/NAS?</b></p>
+
+  <p>Polypaudio is sound daemon similar to ESOUND and NAS, but much more
+  powerful. aRts is a realtime-synthesizer-cum-sound-server, i.e. it
+  does much more than Polypaudio. However, I believe that Polypaudio
+  does what it does much better than any other free sound server.</p>
+  </li>
+
+  <li><p><b>What about ESOUND compatibility?</b></p>
+  <p>Polypaudio is a drop in replacement for ESOUND. That means: you can
+  load a esound compatibility module which implements an ESOUND
+  compatible protocol which allows you to use most of the classic ESOUND
+  compatible programs (including the command line programs like
+  <tt>esdcat</tt>).</p>
+  </li>
+
+  <li><p><b>Is Polypaudio a GNOME program?</b></p>
+  <p>No, Polypaudio has no dependency on GNOME/GTK/GLIB. All it requires
+  is a UNIX-like operating system and very few dependency
+  libraries. However, the accompanying GUI tools are writen with
+  gtkmm, i.e. require both GLIB and GTK.</p></li>
+
+  <li><p><b>Can I integrate Polypaudio in my GLIB/GTK/GNOME application?</b></p>
+  <p>Yes! Polypaudio comes with a GLIB main loop adapter. You can embed
+  both the client library and the daemon (!) into your GLIB based
+  application.</p></li>
+
+  <li><p><b>Can I integrate Polypaudio in my Qt/KDE application?</b></p>
+  <p>Yes! Polypaudio uses a main loop abstraction layer that allows you
+  to integrate Polypaudio in any program that supports main
+  loops. Unfortunately there is no adapter for Qt publicly available yet.</p></li>
+
+  <li><p><b>I want to write a new driver for Polypaudio, are there any docs?</b></p>
+  <p>Currently, only the client API is documented with doxygen. Read
+  the source and base your work on a simple module like
+  <tt>module-pipe-sink</tt>.</p></li>
+
+  <li><p><b>What about compatibility with NAS?</b></p>
+  <p>Is not available (yet?). It is doable, but noone has implemented it yet.</p></li>
+
+  <li><p><b>What about compatibility with aRts?</b></p>
+  <p>Is not available. Since aRts is as synthesizer application you'd have to
+  reimplement very much code for Polypaudio. It should be easy to
+  implement limited support for <tt>libartsc</tt> based
+  applications. Noone has done this yet. It is probably a better idea to
+  run <tt>arts</tt> on top of Polypaudio (through a polypaudio driver
+  for aRts, which nobody has written yet). Another solution would be to
+  embed Polypaudio in the aRts process.</p></li>
+
+  <li><p><b>I often hear noises when playing back with Polypaudio, what can I do?</b></p>
+  <p>There are to possible solutions: either make the polypaudio
+  binary SUID root (<tt>chmod u+s /usr/bin/polypaudio</tt>) and run it
+  with argument <tt>-r</tt> or increase the fragment sizes of the audio
+  drivers. The former will allow Polypaudio to activate
+  <tt>SCHED_FIFO</tt> high priority scheduling (root rights are dropped
+  immediately after this).</p></li>
+
+</ol>
+
+<hr/>
+<address class="grey">Lennart Poettering &lt;@PACKAGE_BUGREPORT@&gt;, September 2004</address>
+<div class="grey"><i>$Id$</i></div>
+</body> </html>
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 6101521cf..723a92c8f 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -17,9 +17,9 @@
 # Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
 
 noinst_DATA = README.html cli.html modules.html daemon.html README
-EXTRA_DIST = $(noinst_DATA) style.css README.html.in cli.html.in modules.html.in daemon.html.in todo
+EXTRA_DIST = $(noinst_DATA) style.css README.html.in cli.html.in modules.html.in daemon.html.in todo FAQ.html.in
 
-MAINTAINERCLEANFILES = README README.html cli.html modules.html daemon.html
+MAINTAINERCLEANFILES = README README.html cli.html modules.html daemon.html FAQ.html
 CLEANFILES =
 
 if USE_LYNX
@@ -34,6 +34,7 @@ tidy: README.html cli.html modules.html daemon.html
 	tidy -e < cli.html
 	tidy -e < daemon.html
 	tidy -e < modules.html
+	tidy -e < FAQ.html
 
 .PHONY: tidy
 
diff --git a/doc/README.html.in b/doc/README.html.in
index f34546328..5af5c4438 100644
--- a/doc/README.html.in
+++ b/doc/README.html.in
@@ -44,9 +44,13 @@ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.</p>
 
 <h2><a name="news">News</a></h2>
 
+<div class="news-date">Wed Sep 8 2004: </div> <p class="news-text"><a
+href="@PACKAGE_URL@polypaudio-0.4.tar.gz">Version 0.4</a> released;
+changes include: daemon auto spawning, support for <tt>SCHED_FIFO</tt> scheduling, three new modules, proper logging, CPU load watchdog, many fixes.</p>
+
 <div class="news-date">Fri Aug 27 2004: </div> <p class="news-text"><a
 href="@PACKAGE_URL@polypaudio-0.3.tar.gz">Version 0.3</a> released;
-changes include: support for both glib 2.0 and glib 1.2, future cancellation, API updates, many fixes; relicense client library to LGPL.</p>
+changes include: support for both glib 2.0 and glib 1.2, future cancellation, API updates, many fixes, relicense client library to LGPL.</p>
 
 <div class="news-date">Fri Aug 20 2004: </div> <p class="news-text"><a
 href="@PACKAGE_URL@polypaudio-0.2.tar.gz">Version 0.2</a> released;
@@ -90,7 +94,10 @@ attempt to write a sound server <a
 href="http://asd.sf.net/">asd</a>.</p>
 
 <p>A GTK GUI manager application for polypaudio is the <a
-href="http://0pointer.de/lennart/projects/paman/">Polypaudio Manager</a>. There are output plugins for <a href="http://0pointer.de/lennart/projects/xmms-polyp/">XMMS</a> and <a href="http://0pointer.de/lennart/projects/libao-polyp/">libao</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
+href="http://0pointer.de/lennart/projects/xmms-polyp/">XMMS</a> and <a
+href="http://0pointer.de/lennart/projects/libao-polyp/">libao</a>.</p>
 
 <h2><a name="status">Status</a></h2>
 
@@ -105,7 +112,7 @@ release to release. The client API's library version number is currently fixed t
 <p>There is some preliminary documentation available: <a
 href="modules.html"><tt>modules.html</tt></a>, <a
 href="cli.html"><tt>cli.html</tt></a>, <a
-href="daemon.html"><tt>daemon.html</tt></a>.</p>
+href="daemon.html"><tt>daemon.html</tt></a>, <a href="FAQ.html"><tt>FAQ.html</tt></a>, .</p>
 
 <h3>First Steps</h3>
 
diff --git a/doc/cli.html.in b/doc/cli.html.in
index 01c04cc9a..6f84a07d9 100644
--- a/doc/cli.html.in
+++ b/doc/cli.html.in
@@ -125,6 +125,10 @@ name.</p>
 
 <p>Play an audio file to a sink. Expects the file name and the sink name as argumens.</p>
 
+<h3><tt>dump</tt></h3>
+
+<p>Dump the daemon's current configuration in CLI commands.</p>
+
 <h2>Killing Clients/Streams</h2>
 
 <h3><tt>kill_client</tt></h3>
@@ -192,6 +196,6 @@ play_file /usr/share/sounds/startup3.wav output
 </pre>
 
 <hr/>
-<address class="grey">Lennart Poettering &lt;@PACKAGE_BUGREPORT@&gt;, August 2004</address>
+<address class="grey">Lennart Poettering &lt;@PACKAGE_BUGREPORT@&gt;, September 2004</address>
 <div class="grey"><i>$Id$</i></div>
 </body> </html>
diff --git a/doc/daemon.html.in b/doc/daemon.html.in
index a5d933dbc..e4903a8ba 100644
--- a/doc/daemon.html.in
+++ b/doc/daemon.html.in
@@ -13,21 +13,28 @@
 
 The <tt>polypaudio</tt> daemon accepts several command line arguments:
 
+<p><tt>-r</tt>: Set low nice value (high priority) and SCHED_FIFO scheduling if available. Works only when started as root or SUID root.</p>
+<p><tt>-R</tt>: Don't drop root rights if started SUID root.</p>
 <p><tt>-L MODULE</tt>: Load the specified module. This option may be specified more than once.</p>
 <p><tt>-F FILE</tt>: Run the specified script. This option may be specified more than once.</p>
 <p><tt>-C</tt>: Load the module <a href="modules.html#module-cli"><tt>module-cli</tt></a> after startup.</p>
+<p><tt>-n</tt>: Don't load the default configuration file. Normally <tt>~/.polypaudio</tt> or <tt>/etc/polyp/polypaudio.pa</tt> are loaded on startup.</p>
 <p><tt>-D</tt>: Daemonize after successfully executing all scripts and loading all modules.</p>
+<p><tt>-d</tt>: Disallow module load and unload after startup.</p>
 <p><tt>-f</tt>: Unless this option is given the daemon will terminate if any of the specified modules failed to load or the script didn't execute successfully.</p>
 <p><tt>-v</tt>: Increase the verbosity of the daemon.</p>
+<p><tt>-X SECS</tt>: Terminate the daemon after the last client exited an SECS seconds passed.</p>
 <p><tt>-h</tt>: Show a quick help.</p>
+<p><tt>-l TARGET</tt>: Specify the log target (<tt>syslog</tt>, <tt>stderr</tt>, <tt>auto</tt>). Defaults to <tt>auto</tt>, which means <tt>stderr</tt> when run without <tt>-D</tt> and <tt>syslog</tt> when run with <tt>-D</tt>.</p>
+<p><tt>-V</tt>: Show version.</p>
 
 <h3>Example</h3>
 
 <p>It is a good idea to run the daemon like this:</p>
 
-<pre>polypaudio -D -F /etc/polypaudio/polypaudio.pa</pre>
+<pre>polypaudio -rD</pre>
 
-<p><tt>/etc/polypaudio/polypaudio.pa</tt> should be a script written in the CLI language described in <a href="cli.html">cli.html</a>
+<p>This will run <tt>/etc/polypaudio/polypaudio.pa</tt> after startup. This should be a script written in the CLI language described in <a href="cli.html">cli.html</a>. </p>
 
 <h2>Signals</h2>
 
@@ -46,6 +53,6 @@ The <tt>polypaudio</tt> daemon accepts several command line arguments:
 <p>The daemon tries to load the module <a href="modules.html#module-cli-protocol-unix"><tt>module-cli-protocol-unix</tt></a>, effectively providing a command line interface on a special UNIX domain socket.</p>
 
 <hr/>
-<address class="grey">Lennart Poettering &lt;@PACKAGE_BUGREPORT@&gt;, July 2004</address>
+<address class="grey">Lennart Poettering &lt;@PACKAGE_BUGREPORT@&gt;, September 2004</address>
 <div class="grey"><i>$Id$</i></div>
 </body> </html>
diff --git a/doc/modules.html.in b/doc/modules.html.in
index fe202989e..22a565d66 100644
--- a/doc/modules.html.in
+++ b/doc/modules.html.in
@@ -30,7 +30,18 @@ special file in the file system. The sink name defaults to <tt>pipe_output</tt>.
 <p>The following option is supported:</p>
 
 <table>
-  <tr><td><tt>file=</tt></td><td>The name of the FIFO special file to use</td></tr>
+  <tr><td><tt>file=</tt></td><td>The name of the FIFO special file to use. (defaults to: <tt>/tmp/music.output</tt>)</td></tr>
+</table>
+
+<h3>module-pipe-source</h3>
+
+<p>Provides a simple test source that reads the audio data from a FIFO
+special file in the file system. The source name defaults to <tt>pipe_input</tt>.</p>
+
+<p>The following option is supported:</p>
+
+<table>
+  <tr><td><tt>file=</tt></td><td>The name of the FIFO special file to use. (defaults to: <tt>/tmp/music.input</tt>)</td></tr>
 </table>
 
 <a name="module-alsa-sink"/>
@@ -184,6 +195,12 @@ about the two possible suffixes of this module.</p>
   <tr><td><tt>cookie=</tt></td><td>Name of the cookie file for authentication purposes</td></tr>
 </table>
 
+<h3>module-native-protocol-fd</h3>
+
+<p>This is used internally when auto spawning a new daemon.</p>
+
+<h2>Miscellaneous</h2>
+
 <h3>module-x11-bell</h3>
 
 <p>Intercepts X11 bell events and plays a sample from the sample cache on each occurence.</p>
@@ -194,7 +211,16 @@ 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-sine</h3>
+
+<p>Creates a sink input and generates a sine waveform stream.</p>
+
+<table>
+  <tr><td><tt>sink=</tt></td><td>The sink to connect to. If ommited defaults to the default sink.</td></tr>
+  <tr><td><tt>frequency=</tt></td><td>The frequency to generate in Hertz. Defaults to 440.</td></tr>
+</table>
+
 <hr/>
-<address class="grey">Lennart Poettering &lt;@PACKAGE_BUGREPORT@&gt;, August 2004</address>
+<address class="grey">Lennart Poettering &lt;@PACKAGE_BUGREPORT@&gt;, September 2004</address>
 <div class="grey"><i>$Id$</i></div>
 </body> </html>
diff --git a/doc/todo b/doc/todo
index 4232a4d42..daed68643 100644
--- a/doc/todo
+++ b/doc/todo
@@ -1,7 +1,5 @@
 *** $Id$ ***
 
-- add FAQ
-
 *** 0.5 ***
 - make mcalign merge chunks
 - use ref counting in more objects (i.e. sink, source, sink_input, source_output)
@@ -13,6 +11,7 @@
 - more complete pactl
 - add sample directory
 - config file for command line arguments
+- option to use default fragment size on alsa drivers
 
 ** later ***
 - xmlrpc/http
diff --git a/polyp/Makefile.am b/polyp/Makefile.am
index 392154972..b5acb3fcf 100644
--- a/polyp/Makefile.am
+++ b/polyp/Makefile.am
@@ -21,7 +21,7 @@ polypincludedir=$(includedir)/polyp
 polypconfdir=$(sysconfdir)/polyp
 
 AM_CFLAGS=-D_GNU_SOURCE -I$(top_srcdir) $(PTHREAD_CFLAGS)
-#AM_CFLAGS+= -DDLSEARCHDIR=\"$(pkglibdir)\" 
+AM_CFLAGS+= -DDLSEARCHDIR=\"$(pkglibdir)\" 
 AM_CFLAGS+="-DDEFAULT_CONFIG_FILE=\"$(polypconfdir)/polypaudio.pa\""
 AM_CFLAGS+="-DPOLYPAUDIO_BINARY=\"$(bindir)/polypaudio\""
 
diff --git a/polyp/module-oss-mmap.c b/polyp/module-oss-mmap.c
index 8151a13af..953871d1b 100644
--- a/polyp/module-oss-mmap.c
+++ b/polyp/module-oss-mmap.c
@@ -249,7 +249,7 @@ int pa_module_init(struct pa_core *c, struct pa_module*m) {
 
     nfrags = 12;
     frag_size = 1024;
-    if (pa_modargs_get_value_s32(ma, "fragments", &nfrags) < 0 || nfrags < 2 || pa_modargs_get_value_s32(ma, "fragment_size", &frag_size) < 0 || frag_size < 1) {
+    if (pa_modargs_get_value_s32(ma, "fragments", &nfrags) < 0 || pa_modargs_get_value_s32(ma, "fragment_size", &frag_size) < 0) {
         pa_log(__FILE__": failed to parse fragments arguments\n");
         goto fail;
     }
@@ -269,9 +269,10 @@ int pa_module_init(struct pa_core *c, struct pa_module*m) {
     }
 
     pa_log(__FILE__": device opened in %s mode.\n", mode == O_WRONLY ? "O_WRONLY" : (mode == O_RDONLY ? "O_RDONLY" : "O_RDWR"));
-    
-    if (pa_oss_set_fragments(u->fd, nfrags, frag_size) < 0)
-        goto fail;
+
+    if (nfrags >= 2 && frag_size >= 1)
+        if (pa_oss_set_fragments(u->fd, nfrags, frag_size) < 0)
+            goto fail;
     
     if (pa_oss_auto_format(u->fd, &u->sample_spec) < 0)
         goto fail;
diff --git a/polyp/module-oss.c b/polyp/module-oss.c
index 53f1f994d..95deca9c1 100644
--- a/polyp/module-oss.c
+++ b/polyp/module-oss.c
@@ -202,7 +202,7 @@ int pa_module_init(struct pa_core *c, struct pa_module*m) {
     
     nfrags = 12;
     frag_size = 1024;
-    if (pa_modargs_get_value_s32(ma, "fragments", &nfrags) < 0 || nfrags < 2 || pa_modargs_get_value_s32(ma, "fragment_size", &frag_size) < 0 || frag_size < 1) {
+    if (pa_modargs_get_value_s32(ma, "fragments", &nfrags) < 0 || pa_modargs_get_value_s32(ma, "fragment_size", &frag_size) < 0) {
         pa_log(__FILE__": failed to parse fragments arguments\n");
         goto fail;
     }
@@ -218,8 +218,10 @@ int pa_module_init(struct pa_core *c, struct pa_module*m) {
 
     pa_log(__FILE__": device opened in %s mode.\n", mode == O_WRONLY ? "O_WRONLY" : (mode == O_RDONLY ? "O_RDONLY" : "O_RDWR"));
 
-    if (pa_oss_set_fragments(fd, nfrags, frag_size) < 0)   
-        goto fail;   
+
+    if (nfrags >= 2 && frag_size >= 1)
+        if (pa_oss_set_fragments(fd, nfrags, frag_size) < 0)   
+            goto fail;   
 
     if (pa_oss_auto_format(fd, &ss) < 0)
         goto fail;
author	Lennart Poettering <lennart@poettering.net>	2004-09-07 22:40:43 +0000
committer	Lennart Poettering <lennart@poettering.net>	2004-09-07 22:40:43 +0000
commit	13248fd8e6cb44e489bd2d77d5ec3491287a1f4d (patch)
tree	29d10ccf6edd075f80d85433fb2a921f52ed0633
parent	70007175d28cf4c7323e772683bbe084e62df024 (diff)