diff options
-rw-r--r-- | doc/FAQ.html.in | 22 | ||||
-rw-r--r-- | doc/README.html.in | 46 | ||||
-rw-r--r-- | doc/cli.html.in | 75 | ||||
-rw-r--r-- | doc/daemon.html.in | 42 | ||||
-rw-r--r-- | doc/modules.html.in | 23 | ||||
-rwxr-xr-x | polyp/default.pa | 14 | ||||
-rw-r--r-- | polyp/main.c | 4 | ||||
-rw-r--r-- | polyp/module-combine.c | 2 |
8 files changed, 160 insertions, 68 deletions
diff --git a/doc/FAQ.html.in b/doc/FAQ.html.in index 074561c1..ac9bc466 100644 --- a/doc/FAQ.html.in +++ b/doc/FAQ.html.in @@ -64,11 +64,29 @@ <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 + with argument <tt>--high-priority=1</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> + immediately after this) Keep in mind that is a potential security hole!</p></li> + <li><p><b>I only want to run polypaudio when it is needed, how do I do this?</b></p> + + <p>Set <tt>autospawn = yes</tt> in <tt>client.conf</tt>. That +configuration file may be found either in <tt>/etc/polypaudio/</tt> or +in <tt>~/.polypaudio/</tt>.</p></li> + + <li><p><b>How do I list all polypaudio modules installed?</b></p> + + <p><tt>polypaudio --dump-modules</tt></p> + + <p>Add <tt>-v</tt> for terse usage instructions.</p> + + <li><p><b>What environment does polypaudio care about?</b></p> + +<p>The client honors: <tt>POLYP_SINK</tt> (default sink to connect to), <tt>POLYP_SOURCE</tt> (default source to connect to), <tt>POLYP_SERVER</tt> (default server to connect to, like <tt>ESPEAKER</tt>), <tt>POLYP_BINARY</tt> (the binary to start when autospawning a daemon), <tt>POLYP_CLIENTCONFIG</tt> (path to the client configuration file).</p> + +<p>The daemon honors: <tt>POLYP_SCRIPT</tt> (default CLI script file run after startup), <tt>POLYP_CONFIG</tt> (default daemon configuration file), <tt>POLYP_DLPATH</tt> (colon separated list of paths where to look for modules)</p></li> + </ol> <hr/> diff --git a/doc/README.html.in b/doc/README.html.in index 837cb012..0a33d6f0 100644 --- a/doc/README.html.in +++ b/doc/README.html.in @@ -44,6 +44,14 @@ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.</p> <h2><a name="news">News</a></h2> +<div class="news-date">Mon Sep 20 2004: </div> <p class="news-text"><a +href="@PACKAGE_URL@polypaudio-0.5.tar.gz">Version 0.5</a> released; +changes include: extensive API improvements, new module +<tt>module-combine</tt> for combining multiple sound cards into one, +gcc 2.95 compatibility, configuration files, add "lazy" samples, +support for source and network latency measurements, add +<tt>module-pipe-source</tt>, many other fixes and improvements.</p> + <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> @@ -79,6 +87,8 @@ Daemon</a> (ESOUND). In addition to the features ESOUND provides <li>Flexible, implicit sample type conversion and resampling</li> <li>"Zero-Copy" architecture</li> <li>Module autoloading</li> + <li>Very accurate latency measurement for playback and recordin.</li> + <li>May be used to combine multiple sound cards to one (with sample rate adjustment)</li> </ul> <p>Both the core and the client API are completely asynchronous making @@ -89,15 +99,35 @@ available through <tt>polyplib</tt> is quite difficult to use there is a simplified synchronous API wrapper <tt>polyplib-simple</tt> available. A simple main loop implementation is available as well.</p> +<p>The following modules are currently available:</p> + +<ul> + <li><tt>module-oss</tt>: driver for Open Sound System audio sinks and sources.</li> + <li><tt>module-oss-mmap</tt>: same as above, but uses <tt>mmap()</tt> access to the audio buffer. Not as compatible</li> + <li><tt>module-alsa-sink</tt>, <tt>module-alsa-source</tt>: drivers for ALSA sinks and sources</li> + <li><tt>module-pipe-sink</tt>, <tt>module-pipe-source</tt>: demonstration module providing UNIX fifos backed sinks/sources</li> + <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> + </ul> + <p><tt>polypaudio</tt> is the successor of my previous, ill-fated -attempt to write a sound server <a +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>. 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 +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> +href="http://0pointer.de/lennart/projects/libao-polyp/">libao</a>. Drivers +for <a href="http://gstreamer.net">gstreamer</a> and <a +href="http://mplayerhq.hu">MPlayer</a> will be released shortly.</p> <h2><a name="status">Status</a></h2> @@ -116,9 +146,9 @@ href="daemon.html"><tt>daemon.html</tt></a>, <a href="FAQ.html"><tt>FAQ.html</tt <h3>First Steps</h3> -<p>Simply start the polypaudio daemon with the argument <tt>-C</tt></p> +<p>Simply start the polypaudio daemon with the argument <tt>-nC</tt></p> -<pre>polypaudio -C</pre> +<pre>polypaudio -nC</pre> <p>This will present you a screen like this:</p> @@ -130,10 +160,12 @@ href="cli.html"><tt>cli.html</tt></a>. Another way to start <tt>polypaudio</tt> is by specifying a configuration script like that one included in the distribution on the command line :</p> -<pre>polypaudio -F polypaudio.pa</pre> +<pre>polypaudio -nF polypaudio.pa</pre> <p>This will load some drivers and protocols automatically.</p> +<p>The best idea is to configure your daemon in <tt>/etc/polypaudio/daemon.conf</tt> and <tt>/etc/polypaudio/default.pa</tt> and to run polypaudio without any arguments.</p> + <h3>Developing polypaudio Clients</h3> <p>You may browse the <a href="http://www.doxygen.org/">Doxygen</a> generated <a @@ -149,7 +181,7 @@ documentation</a> for the client API. (Run <tt>make doxygen</tt> to generate thi <li>Protocol support beyond ESOUND's protocol and the native protocol. (such as NAS or a subset of aRts)</li> <li>New programming interfaces such as XMLRPC or DBUS for controlling the daemon.</li> <li>Hooking audio event sources directly into polypaudio (similar to <tt>module-x11-bell</tt>)</li> - <li>For low latency applications such as VOIP: load the VOIP core directly into polypaudio and have a slim GUI frontend to control it.</li> + <li>For low latency applications such as VOIP: load the VOIP core directly into polypaudio and have a slim GUI frontend to control it.</li> </ul> <p>There is currently no documentation how to write loadable modules diff --git a/doc/cli.html.in b/doc/cli.html.in index 6f84a07d..49e568f8 100644 --- a/doc/cli.html.in +++ b/doc/cli.html.in @@ -28,19 +28,19 @@ commands are supported:</p> <h2>Status Commands</h2> -<h3><tt>modules</tt></h3> +<h3><tt>list-modules</tt></h3> <p>Show all currently loaded modules with their arguments.</p> -<h3><tt>sinks/sources</tt></h3> +<h3><tt>list-sinks/list-sources</tt></h3> <p>Show all currently registered sinks (resp. sources).</p> -<h3><tt>clients</tt></h3> +<h3><tt>list-clients</tt></h3> <p>Show all currently active clients.</p> -<h3><tt>sink_inputs/sink_outputs</tt></h3> +<h3><tt>list-sink-inputs/list-sink-outputs</tt></h3> <p>Show all currently active inputs to sinks (resp. outputs of sources).</p> @@ -56,19 +56,19 @@ and <tt>list</tt> are synonyms for <tt>info</tt>.</p> <h2>Module Management</h2> -<h3><tt>load</tt></h3> +<h3><tt>load-module</tt></h3> <p>Load a module specified by its name and arguments. For most modules it is OK to be loaded more than once.</p> -<h3><tt>unload</tt></h3> +<h3><tt>unload-module</tt></h3> <p>Unload a module specified by its index in the module list as returned by <tt>modules</tt>.</p> <h2>Configuration Commands</h2> -<h3><tt>sink_volume</tt></h3> +<h3><tt>set-sink-volume</tt></h3> <p>Set the volume of the specified sink. You may specify the sink either by its index in the sink list or by its name. The volume should be an @@ -76,12 +76,12 @@ integer value greater or equal than 0 (= muted). Volume 256 (<tt>0x100</tt>) is normal volume, values greater than this amplify the audio signal with clipping.</p> -<h3><tt>sink_input_volume</tt></h3> +<h3><tt>set-sink-input-volume</tt></h3> <p>Set the volume of a sink input specified by its index the the sink input list. The same volume rules apply as with <tt>sink_volume</tt>.</p> -<h3><tt>sink_default/source_default</tt></h3> +<h3><tt>set-default-sink</tt>/<tt>set-default-source</tt></h3> <p>Make a sink (resp. source) the default. You may specify the sink (resp. ssource) by its index in the sink (resp. source) list or by its @@ -89,39 +89,46 @@ name.</p> <h2>Sample Cache</h2> -<h3><tt>scache_list</tt></h3> +<h3><tt>list-samples</tt></h3> <p>Lists the contents of the sample cache.</p> -<h3><tt>scache_play</tt></h3> +<h3><tt>play-sample</tt></h3> <p>Play a sample cache entry to a sink. Expects the sample name and the sink name as arguments.</p> -<h3><tt>sache_remove</tt></h3> +<h3><tt>remove-sample</tt></h3> <p>Remove an entry from the sample cache. Expects the sample name as argument.</p> -<h3><tt>sache_load</tt></h3> +<h3><tt>load-sample</tt></h3> <p>Load an audio file to the sample cache. Expects the file name to load and the desired sample name as arguments.</p> +<h3><tt>load-sample-lazy</tt></h3> + +<p>Create a new entry in the sample cache, but don't load the sample +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> + <h2>Module Autoloading</h2> -<h3><tt>autoload_list</tt></h3> +<h3><tt>list-autoload</tt></h3> <p>Lists all currently defined autoloading entries.</p> -<h3><tt>autoload_sink_add/autoload_source_add</tt></h3> +<h3><tt>add-autoload-sink/add-autoload-source</tt></h3> <p>Adds an autoloading entry for a sink (resp. source). Expects the sink name (resp. source name), the module name and the module arguments as arguments.</p> -<h3><tt>autoload_sink_remove/autoload_source_remove</tt></h3> +<h3><tt>remove-autoload-sink/remove-autoload-source</tt></h3> <p>Remove an autoloading entry. Expects the sink name (resp. source name) as argument.</p> <h2>Miscellaneous Commands</h2> -<h3><tt>play_file</tt></h3> +<h3><tt>play-file</tt></h3> <p>Play an audio file to a sink. Expects the file name and the sink name as argumens.</p> @@ -131,12 +138,12 @@ name.</p> <h2>Killing Clients/Streams</h2> -<h3><tt>kill_client</tt></h3> +<h3><tt>kill-client</tt></h3> <p>Remove a client forcibly from the server. There is no protection that the client reconnects immediately.</p> -<h3><tt>kill_sink_input/kill_source_output</tt></h3> +<h3><tt>kill-sink-input/kill-source-output</tt></h3> <p>Remove a sink input (resp. source output) forcibly from the server. This will not remove the owning client or any other streams @@ -165,34 +172,34 @@ on the interactive command line.</p> <p>Mark the following script as executable (<tt>chmod +x</tt>) and run it for a sensible polypaudio configuration.</p> <pre> -#!/usr/bin/polaudio -F +#!/usr/bin/polaudio -nF # Create autoload entries for the device drivers -autoload_sink_add output module-alsa-sink device=plughw:0,0 rate=48000 sink_name=output -autoload_source_add input load module-alsa-source device=hw:1,0 source_name=input +add-autoload-sink output module-alsa-sink device=plughw:0,0 rate=48000 sink_name=output +add-autoload-sink output2 module-oss device=/dev/dsp1 record=0 sink_name=output2 +add-autoload-sink combined module-combine master=output slaves=output2 sink_name=combined -# Load several protocols -load module-esound-protocol-tcp -load module-simple-protocol-tcp -load module-native-protocol-unix -load module-cli-protocol-unix +add-autoload-source input module-alsa-source device=hw:1,0 source_name=input -# Load the CLI module (This is similar to passing "-C" on the command line of polypaudio) -load module-cli +# Load several protocols +load-module module-esound-protocol-unix +load-module module-simple-protocol-tcp +load-module module-native-protocol-unix +load-module module-cli-protocol-unix # Make some devices default -sink_default output -source_default input +set-default-sink combined +set-default-source input # Don't fail if the audio files referred to below don't exist .nofail # Load an audio to the sample cache for usage with module-x11-bell -scache_load /usr/share/sounds/KDE_Notify.wav x11-bell -load module-x11-bell +load-sample-lazy /usr/share/sounds/KDE_Notify.wav x11-bell +load-module module-x11-bell sample=x11-bell # Play a welcome sound -play_file /usr/share/sounds/startup3.wav output +play-file /usr/share/sounds/startup3.wav combined </pre> <hr/> diff --git a/doc/daemon.html.in b/doc/daemon.html.in index e4903a8b..147ee551 100644 --- a/doc/daemon.html.in +++ b/doc/daemon.html.in @@ -13,28 +13,38 @@ 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> +<pre> + -h, --help Show this help + --version Show version + --dump-conf Dump default configuration + --dump-modules Dump list of available modules + + -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) + --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 + --log-target={auto,syslog,stderr} Specify the log target + -p, --dl-search-path=PATH Set the search path for dynamic shared objects (plugins) + --resample-method=[METHOD] Use the specified resampling method + + -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) + + -n Don't load default script file +</pre> <h3>Example</h3> <p>It is a good idea to run the daemon like this:</p> -<pre>polypaudio -rD</pre> +<pre>polypaudio -D</pre> -<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> +<p>This will run <tt>/etc/polypaudio/default.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> diff --git a/doc/modules.html.in b/doc/modules.html.in index 22a565d6..6967b2a1 100644 --- a/doc/modules.html.in +++ b/doc/modules.html.in @@ -93,6 +93,29 @@ compatible as <tt>module-oss</tt>.</p> <p>This module accepts exactly the same arguments as <a href="#module-oss"><tt>module-oss</tt></a>.</p> +<h3>module-combine</h3> + +<p>This combines two or more sinks into one. A new virtual sink is +allocated. All data written to it is forwarded to all connected +sinks. In aequidistant intervals the sample rates of the output sinks +is recalculated: i.e. even when the sink's crystals deviate (which is +normally the case) output appears synchronously to the human ear. The +resampling required for this may be very CPU intensive.</p> + +<table> + <tr><td><tt>sink_name=</tt></td><td>The name for the combined sink. (defaults to <tt>combined</tt>)</td></tr> + <tr><td><tt>master=</tt></td><td>The name of the first sink to link into the combined think. The sample rate/type is taken from this sink.</td></tr> + <tr><td><tt>slaves=</tt></td><td>Name of additional sinks to link into the combined think, seperated by commas.</td></tr> + <tr><td><tt>adjust_time=</td><td>Time in seconds when to readjust the sample rate of all sinks. (defaults to 20)</td></tr> + <tr><td><tt>resample_method=</td><td>Resampling algorithm to +use. See <tt>libsamplerate</tt>'s documentation for more +information. Use one of <tt>sinc-best-quality</tt>, +<tt>sinc-medium-quality</tt>, <tt>sinc-fastest</tt>, +<tt>zero-order-hold</tt>, <tt>linear</tt>. If the default happens to +be to slow on your machine try using <tt>zero-order-hold</tt>. This +will decrease output quality however. (defaults to +<tt>sinc-fastest</tt>)</td></tr> </table> + <h2>Protocols</h2> <a name="module-cli"/> diff --git a/polyp/default.pa b/polyp/default.pa index ae1fbfcb..a3aaa7c8 100755 --- a/polyp/default.pa +++ b/polyp/default.pa @@ -1,4 +1,4 @@ -#!./polypaudio -rnF +#!./polypaudio -nF # # This file is part of polypaudio. @@ -28,12 +28,12 @@ load-module module-oss device="/dev/dsp" sink_name=output source_name=input reco # Load audio drivers automatically on access -#add-autoload_sink output module-oss device="/dev/dsp" sink_name=output source_name=input -#add-autoload_source input module-oss device="/dev/dsp" sink_name=output source_name=input -#add-autoload_sink output module-oss-mmap device="/dev/dsp" sink_name=output source_name=input -#add-autoload_source input module-oss-mmap device="/dev/dsp" sink_name=output source_name=input -#add-autoload_sink output module-alsa-sink sink_name=output -#add-autoload_source input module-alsa-source source_name=input +#add-autoload-sink output module-oss device="/dev/dsp" sink_name=output source_name=input +#add-autoload-source input module-oss device="/dev/dsp" sink_name=output source_name=input +#add-autoload-sink output module-oss-mmap device="/dev/dsp" sink_name=output source_name=input +#add-autoload-source input module-oss-mmap device="/dev/dsp" sink_name=output source_name=input +#add-autoload-sink output module-alsa-sink sink_name=output +#add-autoload-source input module-alsa-source source_name=input # Load several protocols load-module module-esound-protocol-tcp diff --git a/polyp/main.c b/polyp/main.c index 10774388..dfbd1e4b 100644 --- a/polyp/main.c +++ b/polyp/main.c @@ -180,12 +180,14 @@ int main(int argc, char *argv[]) { retval = 1; } + if (conf->verbose) + pa_log(__FILE__": daemon startup %s.\n", retval ? "failed" : "succeeded"); + goto finish; } close(daemon_pipe[0]); daemon_pipe[0] = -1; - if (conf->auto_log_target) pa_log_set_target(PA_LOG_SYSLOG, NULL); diff --git a/polyp/module-combine.c b/polyp/module-combine.c index 1bb183ec..6952ce6c 100644 --- a/polyp/module-combine.c +++ b/polyp/module-combine.c @@ -40,7 +40,7 @@ PA_MODULE_AUTHOR("Lennart Poettering") PA_MODULE_DESCRIPTION("Combine multiple sinks to one") PA_MODULE_VERSION(PACKAGE_VERSION) -PA_MODULE_USAGE("sink_name=<name for the sink> master=<master sink> slave=<slave sinks> adjust_time=<seconds> resample_method=<method>") +PA_MODULE_USAGE("sink_name=<name for the sink> master=<master sink> slaves=<slave sinks> adjust_time=<seconds> resample_method=<method>") #define DEFAULT_SINK_NAME "combined" #define MEMBLOCKQ_MAXLENGTH (1024*170) |