From e16cdb50bd1a38403cd7aac7922461bc23fe918c Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Fri, 7 Jul 2006 16:05:20 +0000 Subject: remove all docs from tarball since they are now available on pulseaudio.org git-svn-id: file:///home/lennart/svn/public/pulseaudio/trunk@1059 fefdeb5f-60dc-0310-8127-8f9354f1896f --- doc/FAQ.html.in | 295 ------------------------------ doc/Makefile.am | 23 +-- doc/README.html.in | 356 ------------------------------------ doc/cli.html.in | 220 ----------------------- doc/daemon.html.in | 88 --------- doc/modules.html.in | 510 ---------------------------------------------------- doc/style.css | 27 --- 7 files changed, 1 insertion(+), 1518 deletions(-) delete mode 100644 doc/FAQ.html.in delete mode 100644 doc/README.html.in delete mode 100644 doc/cli.html.in delete mode 100644 doc/daemon.html.in delete mode 100644 doc/modules.html.in delete mode 100644 doc/style.css (limited to 'doc') diff --git a/doc/FAQ.html.in b/doc/FAQ.html.in deleted file mode 100644 index 39b7390a..00000000 --- a/doc/FAQ.html.in +++ /dev/null @@ -1,295 +0,0 @@ - - - - -PulseAudio: FAQ - - - - - - -

Frequently Asked Questions

- -
    -

  1. How does PulseAudio compare with ESOUND/aRts/NAS?

    - -

    PulseAudio 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 PulseAudio. However, I believe that PulseAudio - does what it does much better than any other free sound server.

    -
    2. - -

  2. What about ESOUND compatibility?

    -

    PulseAudio 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).

    -
    3. - -

  3. Is PulseAudio a GNOME program?

    -

    No, PulseAudio 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 written with - gtkmm, i.e. require both GLIB and GTK.

    4. - -

  4. Can I integrate PulseAudio in my GLIB/GTK/GNOME application?

    -

    Yes! PulseAudio comes with a GLIB main loop adapter. You can embed - both the client library and the daemon (!) into your GLIB based - application.

    5. - -

  5. Can I integrate PulseAudio in my Qt/KDE application?

    -

    Yes! PulseAudio uses a main loop abstraction layer that allows you - to integrate PulseAudio in any program that supports main - loops. Unfortunately there is no adapter for Qt publicly available yet.

    6. - -

  6. I want to write a new driver for PulseAudio, 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.

    7. - -

  7. What about compatibility with NAS?

    -

    Is not available (yet?). It is doable, but noone has implemented it yet.

    8. - -

  8. What about compatibility with aRts?

    -

    Is not available. Since aRts is as synthesizer application you'd have to - reimplement very much code for PulseAudio. 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 PulseAudio (through a PulseAudio driver - for aRts, which nobody has written yet). Another solution would be to - embed PulseAudio in the aRts process.

    9. - -

  9. I often hear noises when playing back with PulseAudio, what can I do?

    -

    There are to possible solutions: run PulseAudio with argument ---high-priority=1 and make yourself member of the group -realtime, or increase the fragment sizes of the audio - drivers. The former will allow PulseAudio to activate - SCHED_FIFO high priority scheduling (root rights are dropped - immediately after this). Keep in mind that this is a potential security hole!

    10. - -

  10. The pulseaudio executable is installed SUID root by default. Why this? Isn't this a potential security hole?

    - -

    PulseAudio activates SCHED_FIFO scheduling if the user -passes --high-priority=1. This will only succeed when -executed as root, therefore the binary is marked SUID root by -default. Yes, this is a potential security hole. However, PulseAudio -tries its best to minimize the security threat: immediately after -startup PulseAudio drops all capabilities except -CAP_SYS_NICE (At least on systems that support it, like Linux; see man 7 -capabilities for more information). If the calling user is not a -member of the group realtime (which is required to have a GID -< 1000), root rights are dropped immediately. This means, you can -install pulseaudio SUID root, but only a subset of your users (the -members of the group realtime) may make use of realtime -scheduling. Keep in mind that these users might load their own binary -modules into the PulseAudio daemon which may freeze the machine. The -daemon has a minimal protection against CPU hogging (the daemon is -killed after hogging more than 70% CPU for 5 seconds), but this may -be circumvented easily by evildoers.

    11. - -

  11. I want to run PulseAudio only when it is needed, how do I do this?

    - -

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

    12. - -

  12. How do I list all PulseAudio modules installed?

    - -

    pulseaudio --dump-modules

    - -

    Add -v for terse usage instructions.

    - -

  13. How do I use PulseAudio over the network?

    - -

    Just set $PULSE_SERVER to the host name of the PulseAudio -server. For authentication you need the same auth cookies on all sides. For -that copy ~./pulse-cookie to all clients that shall -be allowed to connect.

    - -

    Alternatively the authorization cookies can be stored in the X11 server.

    14. - -

  14. Is PulseAudio capable of providing synchronized audio playback over the network for movie players like mplayer?

    - -

    Yes! Unless your network is congested in some way (i.e. transfer latencies vary strongly) it works perfectly. Drop me an email for experimental patches for MPlayer.

    - -

  15. What environment variables does PulseAudio care about?

    - -

    The client honors: PULSE_SINK (default sink to connect to), PULSE_SOURCE (default source to connect to), PULSE_SERVER (default server to connect to, like ESPEAKER), PULSE_BINARY (the binary to start when autospawning a daemon), PULSE_CLIENTCONFIG (path to the client configuration file).

    - -

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

    16. - - -

  16. I saw that SIGUSR2 provokes loading of the module module-cli-protocol-unix. But how do I make use of that?

    - -

    A brilliant guy named Lennart Poettering once wrote a nifty tool -for that purpose: bidilink. To -connect to a running PulseAudio daemon try using the following commands:

    - -
    killall -USR2 pulseaudio
-bidilink unix-client:/tmp/pulse-$USER/cli
    - -

    BTW: Someone should package this great tool for Debian!

    - -

    New: There's now a tool pacmd that automates sending SIGUSR2 to the daemon and running a bidilink like tool for you.

    -
    17. - -

  17. How do the PulseAudio libraries decide where to connect to?

    -

    The following rule applies:

    -
      -
    1. If the the application using the library specifies a server to connect to it is used. If the connection fails, the library fails too.
      2. -
    2. If the environment variable PULSE_SERVER is defined the library connects to that server. If the connection fails, the library fails too.
      3. -
    3. If $DISPLAY is set, the library tries to connect to that server and looks for the root window property POYLP_SERVER for the host to connect to. If PULSE_COOKIE is set it is used as authentication cookie.
      4. -
    4. If the client configuration file (~/.pulse/client.conf or /etc/pulse/client.conf) sets the server address, the library connects to that server. If the connection fails, the library fails too.
      5. -
    5. The library tries to connect to the default local UNIX socket for PulseAudio servers. If the connection fails, it proceeds with the next item.
      6. -
    6. The library tries to connect to the default local TCP socket for PulseAudio servers. If the connection fails, it proceeds with the next item.
      7. -
    7. If $DISPLAY is set, the library tries to connect to the default TCP port of that host. If the connection fails, it proceeds with the next item.
      8. -
    8. The connection fails.
      9. -
    -
    18. - -

  18. Why the heck does libpulse link against libX11?

    -

    The PulseAudio client libraries look for some X11 root window -properties for the credentials of the PulseAudio server to access. You -may compile PulseAudio without X11 for disabling this feature.

    19. - -

  19. How can I use PulseAudio as an RTP based N:N multicast -conferencing solution for the LAN?

    After loading all the -necessary audio drivers for recording and playback, just load the RTP -reciever and sender modules with default parameters:

    - -
    -load-module module-rtp-send
-load-module module-rtp-recv
-
    - -

    As long as the PulseAudio daemon runs, the microphone data will be -streamed to the network and the data from other hosts is played back -locally. Please note that this may cause quite a lot of traffic. Hence -consider passing rate=8000 format=ulaw channels=1 to the -sender module to save bandwith while still maintaining good quality -for speech transmission.

    20. - -

  20. What is this RTP/SDP/SAP thing all about?

    - -

    RTP is the Realtime Transfer Protocol. It is a well-known -protocol for transferring audio and video data over IP. SDP is the Session -Description Protocol and can be used to describe RTP sessions. SAP -is the Session Announcement Protocol and can be used to -announce RTP sessions that are described with SDP. (Modern SIP based VoIP phones use RTP/SDP for their sessions, too)

    - -

    All three protocols are defined in IETF RFCs (RFC3550, RFC3551, -RFC2327, RFC2327). They can be used in both multicast and unicast -fashions. PulseAudio exclusively uses multicast RTP/SDP/SAP containing audio data.

    - -

    For more information about using these technologies with PulseAudio have a look on the respective module's documentation. - -

  21. How can I use PulseAudio to stream music from my main PC to my LAN with multiple PCs with speakers?

    - -

    On the sender side create an RTP sink:

    - -
    -load-module module-null-sink sink_name=rtp
-load-module module-rtp-send source=rtp_monitor
-set-default-sink rtp
-
    - -

    This will make rtp the default sink, i.e. all applications will write to this virtual RTP device by default.

    - -

    On the client sides just load the reciever module:

    -
    -load-module module-rtp-recv
-
    - -

    Now you can play your favourite music on the sender side and all clients will output it simultaneously.

    - - -

    BTW: You can have more than one sender machine set up like this. The audio data will be mixed on the client side.

    22. - -

  22. How can I use PulseAudio to share a single LINE-IN/MIC jack on the entire LAN?

    - -

    On the sender side simply load the RTP sender module:

    - -
    -load-module module-rtp-send
-
    - -

    On the reciever sides, create an RTP source:

    - -
    -load-module module-null-sink sink_name=rtp
-load-module module-rtp-recv sink=rtp
-set-default-source rtp_monitor
-
    - -

    Now the audio data will be available from the default source rtp_monitor.

    23. - -

  23. When sending multicast RTP traffic it is recieved on the entire LAN but not by the sender machine itself!

    - -

    Pass loop=1 to the sender module!

    24. - -

  24. Can I have more than one multicast RTP group?

    - -

    Yes! Simply use a new multicast group address. Use -the destination/sap_address arguments of the RTP -modules to select them. Choose your group addresses from the range -225.0.0.x to make sure the audio data never leaves the LAN.

    25. - - -

  25. Can I use PulseAudio to playback music on two sound cards simultaneously?

    - -

    Yes! Use module-combine for that.

    - -
    -load-module module-oss-mmap device="/dev/dsp" sink_name=output0
-load-module module-oss-mmap device="/dev/dsp1" sink_name=output1
-load-module module-combine sink_name=combined master=output0 slaves=output1
-set-sink-default combined
-
    - -

    This will combine the two sinks output0 and -output1 into a new sink combined. Every sample -written to the latter will be forwarded to the former two. PulseAudio -will make sure to adjust the sample rate of the slave device in case -it deviates from the master device. You can have more than one slave -sink attached to the combined sink, and hence combine even three and -more sound cards.

    26. - -

  26. Can I use PulseAudio to combine two stereo soundcards into a virtual surround sound card?

    - -

    Yes! You can use use module-combine for that.

    - -
    -load-module module-oss-mmap device="/dev/dsp" sink_name=output0 channel_map=left,right channels=2
-load-module module-oss-mmap device="/dev/dsp1" sink_name=output1 channel_map=rear-left,rear-right channels=2
-load-module module-combine sink_name=combined master=output0 slaves=output1 channel_map=left,right,rear-left,rear-right channels=4
-
    - -

    This is mostly identical to the previous example. However, this -time we manually specify the channel mappings for the sinks to make -sure everything is routed correctly.

    - -

    Please keep in mind that PulseAudio will constantly adjust the -sample rate to compensate for the deviating quartzes of the sound -devices. This is not perfect, however. Deviations in a range of -1/44100s (or 1/48000s depending on the sampling frequency) can not be -compensated. The human ear will decode these deviations as minor -movements (less than 1cm) of the positions of the sound sources -you hear.

    - -
    27. - -

  27. Why did you rename Polypaudio to PulseAudio?

    - -

    Please read this blog story for an explanation.

    - -
    28. - -
- -
-
Lennart Poettering <@PACKAGE_BUGREPORT@>, April 2006
-
$Id$
- diff --git a/doc/Makefile.am b/doc/Makefile.am index a58911ad..1e9fe244 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -16,26 +16,5 @@ # along with PulseAudio; if not, write to the Free Software Foundation, # Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. -noinst_DATA = README.html cli.html modules.html daemon.html FAQ.html -EXTRA_DIST = $(noinst_DATA) style.css README.html.in cli.html.in modules.html.in daemon.html.in todo FAQ.html.in - -MAINTAINERCLEANFILES = README.html cli.html modules.html daemon.html FAQ.html -CLEANFILES = - -if USE_LYNX -README: README.html - lynx --dump $^ | sed 's,file://localhost/.*/doc/README.html,README,' > $@ - -noinst_DATA += README -CLEANFILES += README -endif - -tidy: README.html cli.html modules.html daemon.html - tidy -qe < README.html ; true - tidy -qe < cli.html ; true - tidy -qe < daemon.html ; true - tidy -qe < modules.html ; true - tidy -qe < FAQ.html ; true - -.PHONY: tidy +EXTRA_DIST = todo diff --git a/doc/README.html.in b/doc/README.html.in deleted file mode 100644 index 4937deb3..00000000 --- a/doc/README.html.in +++ /dev/null @@ -1,356 +0,0 @@ - - - - - -PulseAudio @PACKAGE_VERSION@ - - - - -

PulseAudio @PACKAGE_VERSION@

- -

Copyright 2004-2006 Lennart Poettering <@PACKAGE_BUGREPORT@> and Pierre Ossman

- - - -

License

- -

This program is free software; you can redistribute it and/or -modify it under the terms of the GNU Lesser General Public License as -published by the Free Software Foundation; either version 2 of the -License, or (at your option) any later version.

- -

This program is distributed in the hope that it will be useful, but -WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -Lesser General Public License for more details.

- -

You should have received a copy of the GNU Lesser General Public License -along with this program; if not, write to the Free Software -Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

- -

News

- -
Fri Jul 7 2006:

Version 0.9.2 -released; changes include: rename project to PulseAudio (see this blog -article for an explanation); increase maximum number of concurrent -connections; fix latency interpolation; add support for reverse endian -sound cards; add support for recording in padsp; reenable CPU -load limiter; other bugfixes

- -
Fri Jun 2 2006:

Version 0.9.1 -released; changes include: load modules even when libtool .la -files are missing; generate better ALSA device names from -module-detect; if an ALSA device doesn't support the -requested number of channels or the frequency, accept what ALSA -suggests instead; amd64 portability; drop .sh suffix of -esdcompat.sh; build system fixes; No API or ABI changes were made

- -
Fri May 26 2006:

Version 0.9.0 -released; changes include: new module module-volume-restore; -new OSS API emulation tool padsp; require valid UTF8 strings -everywhere; properly support ALSA channel maps for surround sound; -increase maximum number of channels per stream to 32; add new threaded -main loop API for synchronous programs; introduce real shared object -versioning; a few API additions; many, many bugfixes

- -
Fri Apr 28 2006:

Version 0.8.1 -released; changes include: support for specifying the channel map on -the command lines of paplay and pacat and as -arguments to the driver modules; ALSA hardware mixer compatibility; -fix linking; properly remove PF_UNIX sockets when unloading -protocol modules; fix sample cache; many other fixes

- -
Thu Apr 13 2006:

Version 0.8 released; -changes include: too many to count - consider reading this blog entry for more information; many, many minor fixes.

- -
Sun Nov 21 2004:

Version 0.7 released; -changes include: IPv6 support; PID file support; publish credentials -in X11 root window (module-x11-publish; new tool pacmd; ESOUND backend; new command load-sample-dir-lazy; many, many minor fixes.

- -
Thu Oct 28 2004:

Version 0.6 released; -changes include: TCP wrappers support; don't load the complete sound -file into memory when playing back using pa_play_file(); -autoload API change; don't load all sound files as FLOAT32; shorten -default buffers; client-side latency interpolation; add new user -volume metrics; add module-tunnel, module-null-sink, -module-match and new tool paplay; new API version -macros; many client API improvements; correctly lock cookie file -generation; correctly lock daemon autospawning; print daemon layout to -STDERR on SIGHUP; new options for pacat: allow sample type specification.

- -
Mon Sep 24 2004:

Version 0.5.1 released; -changes include: improve esound protocol compatibility; fix -autospawning via libesd; make use of POSIX capabilities; -allow SCHED_FIFO scheduling only for users in group -realtime; minor build system fix.

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

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

- -
Fri Aug 20 2004:

Version 0.2 released; -changes include: added sample cache, introspection API, client API -documentation, module autoloading, glib support, a module for intercepting X11 bell events, and much more.

- -
Sat Jul 17 2004:

Version 0.1 released

- -

Overview

- -

PulseAudio is a networked sound server for Linux and other -Unix like operating systems and Microsoft Windows. It is intended to be an improved drop-in -replacement for the Enlightened Sound -Daemon (ESOUND). In addition to the features ESOUND provides -PulseAudio has:

- - - -

Both the core and the client API are completely asynchronous making -use of a simple main loop abstraction layer. This allows easy -integration with asynchronous applications using the -glib/gtk mainloop. Since the asynchronous API -available through libpulse is quite difficult to use there is -a simplified synchronous API wrapper libpulse-simple -available. A simple main loop implementation is available as well.

- -

The following modules are currently available:

- - - -

A GTK GUI manager application for PulseAudio is the PulseAudio -Manager. Other GTK GUI tool for PulseAudio are the PulseAudio Volume -Meter, PulseAudio Device Chooser and the PulseAudio Volume -Control .

- -

There are output plugins for XMMS, libao -(merged in libao SVN) and gstreamer -(merged in gstreamer-plugins CVS).

- -

PulseAudio was formerly known as Polypaudio.

- -

Current Status

- -

Version @PACKAGE_VERSION@ is quite usable. It matches and supersedes ESOUND's feature set in nearly all areas.

- -

Documentation

- -

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

- -

There is a Trac based Wiki for PulseAudio available.

- -

First Steps

- -

Simply start the PulseAudio daemon with the argument -nC

- -
pulseaudio -nC
- -

This will present you a screen like this:

- -
Welcome to PulseAudio! Use "help" for usage information.
->>>
- -

Now you can issue CLI commands as described in cli.html. Another way to start -PulseAudio is by specifying a configuration script like that one included in the distribution on the -command line :

- -
pulseaudio -nF pulseaudio.pa
- -

This will load some drivers and protocols automatically.

- -

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

- -

Beware! Unless you pass the option --sysconfdir=/etc to -configure, the directory /etc/pulse/ is really -/usr/local/etc/pulse/.

- -

Developing PulseAudio Clients

- -

You may browse the Doxygen generated programing -documentation for the client API. (Run make doxygen to generate this documentation from the source tree)

- -

Developing PulseAudio Modules

- -

There are several reasons for writing loadable modules for PulseAudio:

- - - -

There is currently no documentation how to write loadable modules -for PulseAudio. Read the source, Luke! If you are interested in -writing new modules feel free to contact the author in case you have any -questions.

- -

Requirements

- -

Currently, PulseAudio> is tested on Linux, FreeBSD, Solaris and Microsoft Windows. It requires an OSS, ALSA, Win32 or Solaris compatible soundcard.

- -

PulseAudio was developed and tested on Debian GNU/Linux -"testing" from November 2004, it should work on most other Linux -distributions (and maybe Unix versions) since it uses GNU autoconf and -GNU libtool for source code configuration and shared library -management.

- -

Pulseaudio needs Secret Rabbit Code (aka -libsamplerate), libsndfile, liboil.

- -

Optionally it can make use of libwrap, alsa-lib, libasyncns, -lirc, HOWL (or preferably the compatibility layer included in its superior replacement Avahi) and GLIB. (The latter is required for -building the GLIB main loop integration module only.)

- -

Installation

- -

As this package is made with the GNU autotools you should run -./configure inside the distribution directory for configuring -the source tree. After that you should run make for -compilation and make install (as root) for installation of -PulseAudio.

- -

Acknowledgements

- -

Eric B. Mitchell for writing ESOUND

- -

Jeff Waugh for creating Ubuntu packages (and hopefully soon Debian)

- -

Miguel Freitas for writing a PulseAudio driver for Xine

- -

Joe Marcus Clarke for porting PulseAudio to FreeBSD

- -

Cendio AB for paying for Pierre's work on PulseAudio

- -

Sebastien ESTIENNE for testing

- -

Igor Zubkov for some portability patches

- -

Jan Schmidt for some latency interpolation love

- -

Download

- -

The newest release is always available from @PACKAGE_URL@

- -

The current release is @PACKAGE_VERSION@

- -

Get PulseAudio's development sources from the Subversion repository (ViewCVS, Trac):

- -
svn checkout svn://0pointer.de/pulseaudio/trunk pulseaudio
- -

Community

- -

If you want to be notified whenever I release a new version of this software use the subscription feature of Freshmeat.

- -

There is a general discussion mailing list for PulseAudio available. In addition, you can subscribe to SVN changes and Trac Tickets.

- -

PulseAudio is being tracked at CIA.

- -

There's a chance to meet the PulseAudio developers on our IRC channel #pulseaudio on irc.freenode.org.

- -

The main project homepage is http://pulseaudio.org/.

- -

Please report bugs to our Trac ticket system.

- -
-
Lennart Poettering <@PACKAGE_BUGREPORT@>, July 2006
-
$Id$
- - - diff --git a/doc/cli.html.in b/doc/cli.html.in deleted file mode 100644 index 3a256732..00000000 --- a/doc/cli.html.in +++ /dev/null @@ -1,220 +0,0 @@ - - - - -PulseAudio: Simple Command Line Language - - - - -

Simple Command Line Language

- -

PulseAudio provides a simple command line language used by -configuration scripts as well as the modules module-cli -and module-cli-protocol-{unix,tcp}. Empty lines and lines -beginning with a hashmark (#) are silently ignored. Several -commands are supported:

- -

Miscellaneous Commands

- -

help

- -

Show a quick help on the commands available.

- -

exit

- -

Terminate the daemon. If you want to terminate a CLI connection -("log out") you might want to use C-d.

- -

Status Commands

- -

list-modules

- -

Show all currently loaded modules with their arguments.

- -

list-sinks/list-sources

- -

Show all currently registered sinks (resp. sources).

- -

list-clients

- -

Show all currently active clients.

- -

list-sink-inputs/list-sink-outputs

- -

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

- -

stat

- -

Show some simple statistics about the allocated memory blocks and -the space used by them.

- -

info

- -

A combination of all status commands described above. ls -and list are synonyms for info.

- -

Module Management

- -

load-module

- -

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

- -

unload-module

- -

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

- -

Configuration Commands

- -

set-sink-volume/set-source-volume

- -

Set the volume of the specified sink or source. You may specify the sink/source either -by its index in the sink/source list or by its name. The volume should be an -integer value greater or equal than 0 (= muted). Volume 65536 -(0x10000) is normal volume, values greater than this amplify -the audio signal (with clipping).

- -

set-sink-mute/set-source-mute

- -

Mute or unmute the specified sink our source. You may specify the -sink/source either by its index or by its name. The mute value is -either 0 or 1.

- -

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.

- -

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

- -

Sample Cache

- -

list-samples

- -

Lists the contents of the sample cache.

- -

play-sample

- -

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

- -

remove-sample

- -

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

- -

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.

- -

load-sample-dir-lazy

- -

Load all entries in the specified directory into the sample cache -as lazy entries. A shell globbing expression (e.g. *.wav) may -be appended to the path of the directory to add.

- -

Module Autoloading

- -

list-autoload

- -

Lists all currently defined autoloading entries.

- -

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.

- -

remove-autoload-sink/remove-autoload-source

- -

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

- -

Miscellaneous Commands

- -

play-file

- -

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

- -

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

- -

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 -opened by the client from the server.

- -

Meta Commands

- -

In addition the the commands described above there a few meta -directives supported by the command line interpreter:

- -

.include

- -

Executes the commands from the specified script file.

- -

.fail/.nofail

- -

Enable (resp. disable) that following failing commands will cancel -the execution of the current script file. This is a ignored when used -on the interactive command line.

- -

.verbose/.noverbose

-

Enable (resp. disable) extra verbosity.

- -

Example Configuration Script

- -

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

- -
-#!/usr/bin/polaudio -nF
-
-# Create autoload entries for the device drivers
-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
-
-add-autoload-source input module-alsa-source device=hw:1,0 source_name=input
-
-# 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
-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
-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 combined
-
- -
-
Lennart Poettering <@PACKAGE_BUGREPORT@>, June 2006
-
$Id$
- diff --git a/doc/daemon.html.in b/doc/daemon.html.in deleted file mode 100644 index d90caa2a..00000000 --- a/doc/daemon.html.in +++ /dev/null @@ -1,88 +0,0 @@ - - - - -PulseAudio: Daemon - - - - -

Daemon

- -

Command Line Arguments

- -The PulseAudio daemon accepts several command line arguments: - -
-COMMANDS:
-  -h, --help                            Show this help
-      --version                         Show version
-      --dump-conf                       Dump default configuration
-      --dump-modules                    Dump list of available modules
-  -k  --kill                            Kill a running daemon
-      --check                           Check for a running daemon
-
-OPTIONS:
-  -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
-                                        (one of src-sinc-medium-quality,
-                                        src-sinc-best-quality,src-sinc-fastest
-                                        src-zero-order-hold,src-linear,trivial)
-      --use-pid-file[=BOOL]             Create a PID file
-
-STARTUP SCRIPT:
-  -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
-
-  -n                                    Don't load default script file
-
- -

Example

- -

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

- -
pulseaudio -D
- -

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

- -

Signals

- -

The following signals are trapped specially:

- -

SIGINT

- -

The daemon is shut down cleanly.

- -

SIGUSR1

- -

The daemon tries to load the module module-cli, effectively providing a command line interface on the calling TTY.

- -

SIGUSR2

- -

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

- -

SIGHUP

- -

The daemon logs the current server layout.

- -
-
Lennart Poettering <@PACKAGE_BUGREPORT@>, June 2006
-
$Id$
- diff --git a/doc/modules.html.in b/doc/modules.html.in deleted file mode 100644 index 7f12d9a9..00000000 --- a/doc/modules.html.in +++ /dev/null @@ -1,510 +0,0 @@ - - - - -PulseAudio: Loadable Modules - - - - - -

Loadable Modules

- -

The following loadable modules are provided with the PulseAudio distribution:

- -

Device Drivers

- -

All device driver modules support the following parameters:

- - - - - -
format=The sample format (one of u8, s16, s16le, s16le, float32, float32be, float32le, alaw, ulaw) (defaults to s16)
rate=The sample rate (defaults to 44100)
channels=Audio channels (defaults to 2)
sink_name=, source_name=Name for the sink (resp. source)
channel_map=Channel map. A list of -comma-seperated channel names. The currently defined channel names -are: left, right, mono, center, -front-left, front-right, front-center, -rear-center, rear-left, rear-right, -lfe, subwoofer, front-left-of-center, -front-right-of-center, side-left, -side-right, aux0, aux1 to aux15, -top-center, top-front-left, -top-front-right, top-front-center, -top-rear-left, top-rear-right, -top-rear-center, (Default depends on the number of channels -and the driver)
- -

module-pipe-sink

- -

Provides a simple test sink that writes the audio data to a FIFO -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. (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)
- - -

module-null-sink

- -

Provides a simple null sink. All data written to this sink is silently dropped. This sink is clocked using the system time.

- -

This module doesn't support any special parameters

- - - -

module-alsa-sink

- -

Provides a playback sink for devices supported by the Advanced Linux -Sound Architecture (ALSA). The sink name defaults to alsa_output.

- -

In addition to the general device driver options described above this module supports:

- - - - - -
device=The ALSA device to use. (defaults to "plughw:0,0")
fragments=The desired fragments when opening the device. (defaults to 12)
fragment_size=The desired fragment size in bytes when opening the device (defaults to 1024)
- -

module-alsa-source

- -

Provides a recording source for devices supported by the Advanced -Linux Sound Architecture (ALSA). The source name defaults to alsa_input.

- -

This module supports device=, fragments= and fragment_size= arguments the same way as module-alsa-sink.

- - - -

module-oss

- -

Provides both a sink and a source for playback, resp. recording on -Open Sound System (OSS) compatible devices.

- -

This module supports device= (which defaults to /dev/dsp), fragments= and fragment_size= arguments the same way as module-alsa-sink.

- -

In addition this module supports the following options:

- - - - -
record=Accepts a binary numerical value for enabling (resp. disabling) the recording on this device. (defaults: to 1)
playback=Accepts a binary numerical value for enabling (resp. disabling) the playback on this device. (defaults: to 1)
- -

The sink name (resp. source name) defaults to oss_output (resp. oss_input).

- -

module-oss-mmap

- -

Similar to module-oss but uses memory mapped -(mmap()) access to the input/output buffers of the audio -device. This provides better latency behaviour but is not as -compatible as module-oss.

- -

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

- -

module-solaris

- -

Provides a sink and source for the Solaris audio device.

- -

In addition to the general device driver options described above this module supports:

- - - - - -
record=Accepts a binary numerical value for enabling (resp. disabling) the recording on this device. (defaults: to 1)
playback=Accepts a binary numerical value for enabling (resp. disabling) the playback on this device. (defaults: to 1)
buffer_size=Record buffer size
- -

module-waveout

- -

Provides a sink and source for the Win32 audio device.

- -

This module supports all arguments thet module-oss supports except device=.

- - -

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 sinks' 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)
- -

module-tunnel-{sink,source}

- -

Tunnel a remote sink/source to a local "ghost" -sink/source. Requires a running PulseAudio daemon on the remote server -with module-native-protocol-tcp loaded. It's probably a -better idea to connect to the remote sink/source directly since some -buffer control is lost through this tunneling.

- - - - - - -
server=The server to connect to
source=The source on the remote server. Only available for module-tunnel-source.
sink=The sink on the remote server. Only available for module-tunnel-sink.
cookie=The authentication cookie file to use.
- -

module-esound-sink

- -

Create a playback sink using an ESOUND server as backend. Whenever you can, try to omit this -module since it has many disadvantages including bad latency -and even worse latency measurement.

- - - - -
server=The server to connect to
cookie=The authentication cookie file to use.
- -

Protocols

- - - -

module-cli

- -

Provides the user with a simple command line interface on the -controlling TTY of the daemon. This module may not be loaded more than -once.

- -

For an explanation of the simple command line language used by this -module see cli.html. - - - -
exit_on_eof=Accepts a binary numerical argument specifying whether the daemon shuld exit after an EOF was recieved from STDIN (default: 0)
- - - - - -

module-cli-protocol-{unix,tcp}

- -

An implemenation of a simple command line based protocol for -controlling the PulseAudio daemon. If loaded, the user may -connect with tools like netcat, telnet or -bidilink to the listening sockets and execute commands the -same way as with module-cli.

- -

Beware! Users are not authenticated when connecting to this -service.

- -

This module exists in two versions: with the suffix -unix -the service will listen on an UNIX domain socket in the local file -system. With the suffix -tcp it will listen on a network -transparent TCP/IP socket. (Both IPv6 and IPv4 - if available)

- -

This module supports the following options:

- - - - - - -
port=(only for -tcp) The port number to listen on (defaults to 4712)
loopback=(only for -tcp) Accepts -a numerical binary value. If 1 the socket is bound to the loopback -device, i.e. not publicly accessible. (defaults to 1)
listen=(only for -tcp) The IP address to listen on. If specified, supersedes the value specified in loopback=
socket=(only for -unix) The UNIX socket name (defaults to /tmp/pulse/cli)
- -

module-simple-protocol-{unix,tcp}

- -

An implementation of a simple protocol which allows playback by using -simple tools like netcat. Just connect to the listening -socket of this module and write the audio data to it, or read it from -it for playback, resp. recording.

- -

Beware! Users are not authenticated when connecting to this -service.

- -

See module-cli-protocol-{unix,tcp} for more information -about the two possible suffixes of this module.

- -

In addition to the options supported by module-cli-protocol-*, this module supports:

- - - - - -
rate=, format=, channels=Sample format for streams connecting to this service.
playback=, record=Enable/disable playback/recording
sink=, source=Specify the sink/source this service connects to
- -

module-esound-protocol-{unix,tcp}

- -

An implemenation of a protocol compatible with the Enlightened Sound -Daemon (ESOUND, esd). When you load this module you may -access the PulseAudio daemon with tools like esdcat, -esdrec or even esdctl. Many applications, such as -XMMS, include support for this protocol.

- -

See module-cli-protocol-{unix,tcp} for more information -about the two possible suffixes of this module.

- -

In addition to the options supported by module-cli-protocol-*, this module supports:

- - - - - -
sink=, source=Specify the sink/source this service connects to
auth-anonymous=If set to 1 no authentication is required to connect to the service
cookie=Name of the cookie file for authentication purposes
- -

This implementation misses some features the original ESOUND has: e.g. there is no sample cache yet. However: XMMS works fine.

- -

module-native-protocol-{unix,tcp}

- -

The native protocol of PulseAudio.

- -

See module-cli-protocol-{unix,tcp} for more information -about the two possible suffixes of this module.

- -

In addition to the options supported by module-cli-protocol-*, this module supports:

- - - - - -
auth-anonymous=If set to 1 no authentication is required to connect to the service
auth-group=(only for -unix): members of the specified unix group may access the server without further auhentication.
cookie=Name of the cookie file for authentication purposes
- -

module-native-protocol-fd

- -

This is used internally when auto spawning a new daemon. Don't use it directly.

- -

module-http-protocol-tcp

- -

A proof-of-concept HTTP module, which can be used to introspect -the current status of the PulseAudio daemon using HTTP. Just load this -module and point your browser to http://localhost:4714/. This module takes the same arguments -as module-cli-protocol-tcp.

- -

X Window System

- -

module-x11-bell

- -

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

- - - - - -
display=X11 display to connect to. If ommited defaults to the value of $DISPLAY
sample=The sample to play. If ommited defaults to x11-bell.
sink=Name of the sink to play the sample on. If ommited defaults to the default sink.
- -

module-x11-publish

- -

Publishes the access credentials to the PulseAudio server in the -X11 root window. The following properties are used: -PULSE_SERVER, POYLP_SINK, PULSE_SOURCE, -PULSE_COOKIE. This is very useful when using SSH or any other -remote login tool for logging into other machines and getting audio -playback to your local speakers. The PulseAudio client libraries make -use of this data automatically. Instead of using this module you may -use the tool pax11publish which may be used to access, modify -and import credential data from/to the X11 display.

- - - - - -
display=X11 display to connect to. If ommited defaults to the value of $DISPLAY
sink=Name of the default sink. If ommited this property isn't stored in the X11 display.
source=Name of the default source. If ommited this property isn't stored in the X11 display.
cookie=Name of the cookie file of the -cookie to store in the X11 display. If ommited the cookie of an -already loaded protocol module is used.
- -

Volume Control

- -

module-mmkbd-evdev

- -

Adjust the volume of a sink when the special multimedia buttons of modern keyboards are pressed.

- - - - -
device=Linux input device ("evdev", defaults to /dev/input/event0)
sink=The sink to control
- -

module-lirc

- -

Adjust the volume of a sink when the volume buttons of an infrared remote control are pressed (through LIRC).

- - - - - -
config=The LIRC configuration file
appname=The application name to pass to LIRC (defaults to pulseaudio)
sink=The sink to control
- - -

RTP/SDP/SAP Transport

- -

PulseAudio can stream audio data to an IP multicast group via the -standard protocols RTP, -SAP -and SDP -(RFC3550, RFC3551, RFC2327, RFC2327). This can be used for multiple -different purposes: for sharing a single microphone on multiple -computers on the local LAN, for streaming music from a single -controlling PC to multiple PCs with speakers or to implement a simple -"always-on" teleconferencing solution.

- -

The current implementation is designed to be used exlusively in -local area networks, though Internet multicasting is theoretically -supported. Only uncompressed audio is supported, hence you won't be -able to multicast more than a few streams at the same time over a -standard LAN.

- -

PulseAudio implements both a sender and a reciever for RTP -traffic. The sender announces itself via SAP/SDP on the same multicast -group as it sends the RTP data to. The reciever picks up the SAP/SDP -announcements and creates a playback stream for each -session. Alternatively you can use any RTP capable client to -recieve and play back the RTP data (such as mplayer).

- -

module-rtp-send

- -

This is the sender side of the RTP/SDP/SAP implementation. It reads -audio data from an existing source and forwards it to the network -encapsulated in RTP. In addition it sends SAP packets with an SDP -session description.

- -

In combination with the monitor source of module-null-sink -you can use this module to create an RTP sink.

- - - - - - - - -
source=The source to read the audio data from. If ommited defaults to the default source.
format=, rate=, channels=Sample format to use, defaults to the source's.
destination=Destination multicast group for both RTP and SAP packets, defaults to 224.0.0.56
port=Destination port number of the RTP -traffic. If ommited defaults to a randomly chosen even port -number. Please keep in mind that the RFC suggests to use only even -port numbers for RTP traffic.
mtu=Maximum payload size for RTP packets. If ommited defaults to 1280
loop=Takes a boolean value, specifying whether locally generated RTP traffic should be looped back to the local host. Disabled by default.
- -

module-rtp-recv

- -

This is the reciever side of the RTP/SDP/SAP implementation. It -picks up SAP session announcements and creates an RTP playback stream -for each.

- -

In combination with module-null-sink you can use this -module to create an RTP source.

- - - - -
sink=The sink to connect to. If ommited defaults to the default sink.
sap_address=The multicast group to join for SAP announcements, defaults to 224.0.0.56.
- -

JACK Connectivity

- -

PulseAudio can be hooked up to a JACK Audio Connection Kit server which is a specialized sound server used for professional audio production on Unix/Linux. Both a -PulseAudio sink and a source are available. For each channel a port is -created in the JACK server.

- -

module-jack-sink

- -

This module implements a PulseAudio sink that connects to JACK and registers as many output ports as requested.

- - - - - - - -
sink_name=The name for the PulseAudio sink. If ommited defaults to jack_out.
server_name=The JACK server to connect to. If ommited defaults to the default server.
client_name=The client name to tell the JACK server. If ommited defaults to PulseAudio.
channels=Number of channels to register. If ommited defaults to the number of physical playback ports of the JACK server.
connect=Takes a boolean value. If enabled (the default) PulseAudio will try to connect its ports to the physicial playback ports of the JACK server
- -

module-jack-source

- -

This module implements a PulseAudio source that connects to JACK -and registers as many input ports as requested. Takes the same -arguments as module-jack-sink, except for sink_name -which is replaced by source_name (with a default of jack_in) for obvious reasons.

- -

Miscellaneous

- -

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

module-esound-compat-spawnfd

- -

This is a compatibility module for libesd based autospawning of PulseAudio. Don't use it directly.

- -

module-esound-compat-spawnpid

- -

This is a compatibility module for libesd based autospawning of PulseAudio. Don't use it directly.

- -

module-match

- -

Adjust the volume of a playback stream automatically based on its name.

- - - -
table=The regular expression matching table file to use (defaults to ~/.pulse/match.table)
- -

The table file should contain a regexp and volume on each line, seperated by spaces. An example:

- -
-^sample: 32000
-
- -

The volumes of all streams with titles starting with sample: are automatically set to 32000. (FYI: All sample cache streams start with sample:)

- -

module-volume-restore

- -

Adjust the volume of a playback stream automatically based on its name.

- - - -
table=The table file to use (defaults to ~/.pulse/volume.table)
- -

In contrast to module-match this module needs no explicit -configuration. Instead the volumes are saved and restored in a fully -automatical fashion depending on the client name to identify -streams. The volume for a stream is automatically saved every time it is -changed and than restored when a new stream is created.

- -

module-detect

- -

Automatically detect the available sound hardware and load modules for it. Supports OSS, ALSA, Solaris and Win32 output drivers. - - - -
just-one=If set to 1 the module will only try to load a single sink/source and than stop.
- -

module-zeroconf-publish

- -

Publish all local sinks/sources using mDNS Zeroconf.

- - -
-
Lennart Poettering <@PACKAGE_BUGREPORT@>, April 2006
-
$Id$
- diff --git a/doc/style.css b/doc/style.css deleted file mode 100644 index c5af0055..00000000 --- a/doc/style.css +++ /dev/null @@ -1,27 +0,0 @@ -/* $Id$ */ - -/*** - * This file is part of PulseAudio. - * - * PulseAudio is free software; you can redistribute it and/or modify it - * under the terms of the GNU Lesser General Public License as published by - * the Free Software Foundation; either version 2 of the License, or - * (at your option) any later version. - * - * PulseAudio is distributed in the hope that it will be useful, but - * WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - * General Public License for more details. - * - * You should have received a copy of the GNU Lesser General Public License - * along with PulseAudio; if not, write to the Free Software Foundation, - * Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. - ***/ - -body { color: black; background-color: white; } -a:link, a:visited { color: #900000; } -div.news-date { font-size: 80%; font-style: italic; } -pre { background-color: #f0f0f0; padding: 0.4cm; } -.grey { color: #8f8f8f; font-size: 80%; } -table { margin-left: 1cm; border:1px solid lightgrey; padding: 0.2cm; } -td { padding-left:10px; padding-right:10px; } -- cgit