summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorLennart Poettering <lennart@poettering.net>2004-09-07 22:40:43 +0000
committerLennart Poettering <lennart@poettering.net>2004-09-07 22:40:43 +0000
commit13248fd8e6cb44e489bd2d77d5ec3491287a1f4d (patch)
tree29d10ccf6edd075f80d85433fb2a921f52ed0633
parent70007175d28cf4c7323e772683bbe084e62df024 (diff)
documentation update
git-svn-id: file:///home/lennart/svn/public/pulseaudio/trunk@185 fefdeb5f-60dc-0310-8127-8f9354f1896f
-rw-r--r--configure.ac4
-rw-r--r--doc/FAQ.html.in77
-rw-r--r--doc/Makefile.am5
-rw-r--r--doc/README.html.in13
-rw-r--r--doc/cli.html.in6
-rw-r--r--doc/daemon.html.in13
-rw-r--r--doc/modules.html.in30
-rw-r--r--doc/todo3
-rw-r--r--polyp/Makefile.am2
-rw-r--r--polyp/module-oss-mmap.c9
-rw-r--r--polyp/module-oss.c8
11 files changed, 147 insertions, 23 deletions
diff --git a/configure.ac b/configure.ac
index f221689d..d278ff8e 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 00000000..074561c1
--- /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 6101521c..723a92c8 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 f3454632..5af5c443 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 01c04cc9..6f84a07d 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 a5d933db..e4903a8b 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 fe202989..22a565d6 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 4232a4d4..daed6864 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 39215497..b5acb3fc 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 8151a13a..953871d1 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 53f1f994..95deca9c 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;