From 13248fd8e6cb44e489bd2d77d5ec3491287a1f4d Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Tue, 7 Sep 2004 22:40:43 +0000 Subject: documentation update git-svn-id: file:///home/lennart/svn/public/pulseaudio/trunk@185 fefdeb5f-60dc-0310-8127-8f9354f1896f --- configure.ac | 4 +-- doc/FAQ.html.in | 77 +++++++++++++++++++++++++++++++++++++++++++++++++ doc/Makefile.am | 5 ++-- doc/README.html.in | 13 +++++++-- doc/cli.html.in | 6 +++- doc/daemon.html.in | 13 +++++++-- doc/modules.html.in | 30 +++++++++++++++++-- doc/todo | 3 +- polyp/Makefile.am | 2 +- polyp/module-oss-mmap.c | 9 +++--- polyp/module-oss.c | 8 +++-- 11 files changed, 147 insertions(+), 23 deletions(-) create mode 100644 doc/FAQ.html.in 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 @@ + + + + +polypaudio: FAQ + + + + + + +

Frequently Asked Questions

+ +

How does Polypaudio compare with ESOUND/aRts/NAS?
+ +
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.
+
What about ESOUND compatibility?
+
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 + esdcat).
+
Is Polypaudio a GNOME program?
+
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.
Can I integrate Polypaudio in my GLIB/GTK/GNOME application?
+
Yes! Polypaudio comes with a GLIB main loop adapter. You can embed + both the client library and the daemon (!) into your GLIB based + application.
Can I integrate Polypaudio in my Qt/KDE application?
+
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.
I want to write a new driver for Polypaudio, are there any docs?
+
Currently, only the client API is documented with doxygen. Read + the source and base your work on a simple module like + module-pipe-sink.
What about compatibility with NAS?
+
Is not available (yet?). It is doable, but noone has implemented it yet.
What about compatibility with aRts?
+
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 libartsc based + applications. Noone has done this yet. It is probably a better idea to + run arts 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.
I often hear noises when playing back with Polypaudio, what can I do?
+
There are to possible solutions: either make the polypaudio + binary SUID root (chmod u+s /usr/bin/polypaudio) and run it + with argument -r or increase the fragment sizes of the audio + drivers. The former will allow Polypaudio to activate + SCHED_FIFO high priority scheduling (root rights are dropped + immediately after this).

+ +

Lennart Poettering <@PACKAGE_BUGREPORT@>, September 2004

$Id$

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

News

Wed Sep 8 2004:

Version 0.4 released; +changes include: daemon auto spawning, support for SCHED_FIFO scheduling, three new modules, proper logging, CPU load watchdog, many fixes.

Fri Aug 27 2004:

Version 0.3 released; -changes include: support for both glib 2.0 and glib 1.2, future cancellation, API updates, many fixes; relicense client library to LGPL.

+changes include: support for both glib 2.0 and glib 1.2, future cancellation, API updates, many fixes, relicense client library to LGPL.

Fri Aug 20 2004:

Version 0.2 released; @@ -90,7 +94,10 @@ attempt to write a sound server asd.

A GTK GUI manager application for polypaudio is the Polypaudio Manager. There are output plugins for XMMS and libao.

+href="http://0pointer.de/lennart/projects/paman/">Polypaudio +Manager. Another GTK GUI tool for Polypaudio is the Polypaudio Volume Meter. There are output plugins for XMMS and libao.

Status

@@ -105,7 +112,7 @@ release to release. The client API's library version number is currently fixed t

There is some preliminary documentation available: modules.html, cli.html, daemon.html.

+href="daemon.html">daemon.html, FAQ.html, .

First Steps

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.

Play an audio file to a sink. Expects the file name and the sink name as argumens.

`dump`

+ +

Dump the daemon's current configuration in CLI commands.

Killing Clients/Streams

`kill_client`

@@ -192,6 +196,6 @@ play_file /usr/share/sounds/startup3.wav output

Lennart Poettering <@PACKAGE_BUGREPORT@>, August 2004

Lennart Poettering <@PACKAGE_BUGREPORT@>, September 2004

$Id$

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 polypaudio daemon accepts several command line arguments: +

-r: Set low nice value (high priority) and SCHED_FIFO scheduling if available. Works only when started as root or SUID root.

-R: Don't drop root rights if started SUID root.

-L MODULE: Load the specified module. This option may be specified more than once.

-F FILE: Run the specified script. This option may be specified more than once.

-C: Load the module module-cli after startup.

-n: Don't load the default configuration file. Normally ~/.polypaudio or /etc/polyp/polypaudio.pa are loaded on startup.

-D: Daemonize after successfully executing all scripts and loading all modules.

-d: Disallow module load and unload after startup.

-f: 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.

-v: Increase the verbosity of the daemon.

-X SECS: Terminate the daemon after the last client exited an SECS seconds passed.

-h: Show a quick help.

-l TARGET: Specify the log target (syslog, stderr, auto). Defaults to auto, which means stderr when run without -D and syslog when run with -D.

-V: Show version.

Example

It is a good idea to run the daemon like this:

polypaudio -D -F /etc/polypaudio/polypaudio.pa

polypaudio -rD

/etc/polypaudio/polypaudio.pa should be a script written in the CLI language described in cli.html +

This will run /etc/polypaudio/polypaudio.pa after startup. This should be a script written in the CLI language described in cli.html.

Signals

@@ -46,6 +53,6 @@ The polypaudio daemon accepts several command line arguments:

The daemon tries to load the module module-cli-protocol-unix, effectively providing a command line interface on a special UNIX domain socket.

Lennart Poettering <@PACKAGE_BUGREPORT@>, July 2004

Lennart Poettering <@PACKAGE_BUGREPORT@>, September 2004

$Id$

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

The following option is supported:

- + +

`file=`	The name of the FIFO special file to use
`file=`	The name of the FIFO special file to use. (defaults to: `/tmp/music.output`)

+ +

module-pipe-source

+ +

Provides a simple test source that reads the audio data from a FIFO +special file in the file system. The source name defaults to pipe_input.

+ +

The following option is supported:

+ + +

file= The name of the FIFO special file to use. (defaults to: /tmp/music.input)

@@ -184,6 +195,12 @@ about the two possible suffixes of this module.

cookie=Name of the cookie file for authentication purposes +

module-native-protocol-fd

+ +

This is used internally when auto spawning a new daemon.

+ +

Miscellaneous

module-x11-bell

Intercepts X11 bell events and plays a sample from the sample cache on each occurence.

@@ -194,7 +211,16 @@ about the two possible suffixes of this module.

sink=Name of the sink to play the sample on. If ommited defaults to the default sink. +

module-sine

+ +

Creates a sink input and generates a sine waveform stream.

+ + + + +

`sink=`	The sink to connect to. If ommited defaults to the default sink.
`frequency=`	The frequency to generate in Hertz. Defaults to 440.

Lennart Poettering <@PACKAGE_BUGREPORT@>, August 2004

Lennart Poettering <@PACKAGE_BUGREPORT@>, September 2004

$Id$

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; -- cgit