From 2d87bd2d2f088220ccf98af93073cfd807dc2d1b Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Mon, 20 Sep 2004 20:52:35 +0000 Subject: documentation update git-svn-id: file:///home/lennart/svn/public/pulseaudio/trunk@225 fefdeb5f-60dc-0310-8127-8f9354f1896f --- doc/FAQ.html.in | 22 +++++++++++++-- doc/README.html.in | 46 ++++++++++++++++++++++++++----- doc/cli.html.in | 75 +++++++++++++++++++++++++++----------------------- doc/daemon.html.in | 42 +++++++++++++++++----------- doc/modules.html.in | 23 ++++++++++++++++ polyp/default.pa | 14 +++++----- polyp/main.c | 4 ++- 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 @@

  • 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 + with argument --high-priority=1 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).

    • + immediately after this) Keep in mind that is a potential security hole!

    +

  • I only want to run polypaudio when it is needed, how do I do this?

    + +

    Set autospawn = yes in client.conf. That +configuration file may be found either in /etc/polypaudio/ or +in ~/.polypaudio/.

    • + +

  • How do I list all polypaudio modules installed?

    + +

    polypaudio --dump-modules

    + +

    Add -v for terse usage instructions.

    + +

  • What environment does polypaudio care about?

    + +

    The client honors: POLYP_SINK (default sink to connect to), POLYP_SOURCE (default source to connect to), POLYP_SERVER (default server to connect to, like ESPEAKER), POLYP_BINARY (the binary to start when autospawning a daemon), POLYP_CLIENTCONFIG (path to the client configuration file).

    + +

    The daemon honors: POLYP_SCRIPT (default CLI script file run after startup), POLYP_CONFIG (default daemon configuration file), POLYP_DLPATH (colon separated list of paths where to look for modules)

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

    News

    +
    Mon Sep 20 2004:

    Version 0.5 released; +changes include: extensive API improvements, new module +module-combine for combining multiple sound cards into one, +gcc 2.95 compatibility, configuration files, add "lazy" samples, +support for source and network latency measurements, add +module-pipe-source, many other fixes and improvements.

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

    @@ -79,6 +87,8 @@ Daemon (ESOUND). In addition to the features ESOUND provides
  • Flexible, implicit sample type conversion and resampling
  • "Zero-Copy" architecture
  • Module autoloading
    • +
  • Very accurate latency measurement for playback and recordin.
    • +
  • May be used to combine multiple sound cards to one (with sample rate adjustment)

    • Both the core and the client API are completely asynchronous making @@ -89,15 +99,35 @@ available through polyplib is quite difficult to use there is a simplified synchronous API wrapper polyplib-simple available. A simple main loop implementation is available as well.

    +

    The following modules are currently available:

    + + +

    polypaudio is the successor of my previous, ill-fated -attempt to write a sound server asd.

    A GTK GUI manager application for polypaudio is the Polypaudio -Manager. Another GTK GUI tool for Polypaudio is the Polypaudio Volume Meter. There are output plugins for . Another GTK GUI tool for Polypaudio is the Polypaudio Volume +Meter. There are output plugins for XMMS and libao.

    +href="http://0pointer.de/lennart/projects/libao-polyp/">libao. Drivers +for gstreamer and MPlayer will be released shortly.

    Status

    @@ -116,9 +146,9 @@ href="daemon.html">daemon.html, FAQ.htmlFirst Steps -

    Simply start the polypaudio daemon with the argument -C

    +

    Simply start the polypaudio daemon with the argument -nC

    -
    polypaudio -C
    +
    polypaudio -nC

    This will present you a screen like this:

    @@ -130,10 +160,12 @@ href="cli.html">cli.html    . Another way to start polypaudio is by specifying a configuration script like that one included in the distribution on the command line :

    -
    polypaudio -F polypaudio.pa
    +
    polypaudio -nF polypaudio.pa

    This will load some drivers and protocols automatically.

    +

    The best idea is to configure your daemon in /etc/polypaudio/daemon.conf and /etc/polypaudio/default.pa and to run polypaudio without any arguments.

    +

    Developing polypaudio Clients

    You may browse the Doxygen generated for the client API. (Run make doxygen to generate thi

  • Protocol support beyond ESOUND's protocol and the native protocol. (such as NAS or a subset of aRts)
  • New programming interfaces such as XMLRPC or DBUS for controlling the daemon.
  • Hooking audio event sources directly into polypaudio (similar to module-x11-bell)
    • -
  • For low latency applications such as VOIP: load the VOIP core directly into polypaudio and have a slim GUI frontend to control it.
    • +
  • For low latency applications such as VOIP: load the VOIP core directly into polypaudio and have a slim GUI frontend to control it.

    • 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:

    Status Commands

    -

    modules

    +

    list-modules

    Show all currently loaded modules with their arguments.

    -

    sinks/sources

    +

    list-sinks/list-sources

    Show all currently registered sinks (resp. sources).

    -

    clients

    +

    list-clients

    Show all currently active clients.

    -

    sink_inputs/sink_outputs

    +

    list-sink-inputs/list-sink-outputs

    Show all currently active inputs to sinks (resp. outputs of sources).

    @@ -56,19 +56,19 @@ and list are synonyms for info.

    Module Management

    -

    load

    +

    load-module

    Load a module specified by its name and arguments. For most modules it is OK to be loaded more than once.

    -

    unload

    +

    unload-module

    Unload a module specified by its index in the module list as returned by modules.

    Configuration Commands

    -

    sink_volume

    +

    set-sink-volume

    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 (0x100) is normal volume, values greater than this amplify the audio signal with clipping.

    -

    sink_input_volume

    +

    set-sink-input-volume

    Set the volume of a sink input specified by its index the the sink input list. The same volume rules apply as with sink_volume.

    -

    sink_default/source_default

    +

    set-default-sink/set-default-source

    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.

    Sample Cache

    -

    scache_list

    +

    list-samples

    Lists the contents of the sample cache.

    -

    scache_play

    +

    play-sample

    Play a sample cache entry to a sink. Expects the sample name and the sink name as arguments.

    -

    sache_remove

    +

    remove-sample

    Remove an entry from the sample cache. Expects the sample name as argument.

    -

    sache_load

    +

    load-sample

    Load an audio file to the sample cache. Expects the file name to load and the desired sample name as arguments.

    +

    load-sample-lazy

    + +

    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.

    +

    Module Autoloading

    -

    autoload_list

    +

    list-autoload

    Lists all currently defined autoloading entries.

    -

    autoload_sink_add/autoload_source_add

    +

    add-autoload-sink/add-autoload-source

    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.

    -

    autoload_sink_remove/autoload_source_remove

    +

    remove-autoload-sink/remove-autoload-source

    Remove an autoloading entry. Expects the sink name (resp. source name) as argument.

    Miscellaneous Commands

    -

    play_file

    +

    play-file

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

    @@ -131,12 +138,12 @@ name.

    Killing Clients/Streams

    -

    kill_client

    +

    kill-client

    Remove a client forcibly from the server. There is no protection that the client reconnects immediately.

    -

    kill_sink_input/kill_source_output

    +

    kill-sink-input/kill-source-output

    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.

    Mark the following script as executable (chmod +x) and run it for a sensible polypaudio configuration.

    -#!/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
    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 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.

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

    Example

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

    -
    polypaudio -rD
    +
    polypaudio -D
    -

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

    +

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

    Signals

    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 module-oss.

    This module accepts exactly the same arguments as module-oss.

    +

    module-combine

    + +

    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.

    + + + + + + +
    sink_name=The name for the combined sink. (defaults to combined)
    master=The name of the first sink to link into the combined think. The sample rate/type is taken from this sink.
    slaves=Name of additional sinks to link into the combined think, seperated by commas.
    adjust_time=Time in seconds when to readjust the sample rate of all sinks. (defaults to 20)
    resample_method=Resampling algorithm to +use. See libsamplerate's documentation for more +information. Use one of sinc-best-quality, +sinc-medium-quality, sinc-fastest, +zero-order-hold, linear. If the default happens to +be to slow on your machine try using zero-order-hold. This +will decrease output quality however. (defaults to +sinc-fastest)
    +

    Protocols

    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= master= slave= adjust_time= resample_method=") +PA_MODULE_USAGE("sink_name= master= slaves= adjust_time= resample_method=") #define DEFAULT_SINK_NAME "combined" #define MEMBLOCKQ_MAXLENGTH (1024*170) -- cgit