From 7b8c329578d642d31618d487b97864306c43073c Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Sat, 17 Jul 2004 14:06:13 +0000 Subject: add documentation git-svn-id: file:///home/lennart/svn/public/pulseaudio/trunk@86 fefdeb5f-60dc-0310-8127-8f9354f1896f --- doc/Makefile.am | 39 +++++++++++ doc/README.html.in | 133 ++++++++++++++++++++++++++++++++++++ doc/cli.html.in | 152 +++++++++++++++++++++++++++++++++++++++++ doc/daemon.html.in | 51 ++++++++++++++ doc/modules.html.in | 191 ++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/style.css | 34 ++++++++++ 6 files changed, 600 insertions(+) create mode 100644 doc/Makefile.am create mode 100644 doc/README.html.in create mode 100644 doc/cli.html.in create mode 100644 doc/daemon.html.in create mode 100644 doc/modules.html.in create mode 100644 doc/style.css (limited to 'doc') diff --git a/doc/Makefile.am b/doc/Makefile.am new file mode 100644 index 00000000..015d503d --- /dev/null +++ b/doc/Makefile.am @@ -0,0 +1,39 @@ +# $Id$ + +# This file is part of polypaudio. +# +# polypaudio is free software; you can redistribute it and/or modify it +# under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# polypaudio 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 General Public License +# along with polypaudio; 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 README +EXTRA_DIST = $(noinst_DATA) style.css README.html.in cli.html.in modules.html.in daemon.html.in + +MAINTAINERCLEANFILES = README README.html cli.html modules.html daemon.html +CLEANFILES = + +if USE_LYNX +README: README.html + lynx --dump $^ | sed 's,file://localhost/.*/doc/README.html,README,' > $@ + +CLEANFILES += README +endif + +tidy: README.html cli.html modules.html daemon.html + tidy -e < README.html + tidy -e < cli.html + tidy -e < modules.html + tidy -e < daemon.html + +.PHONY: tidy + diff --git a/doc/README.html.in b/doc/README.html.in new file mode 100644 index 00000000..a9b07d60 --- /dev/null +++ b/doc/README.html.in @@ -0,0 +1,133 @@ + + + + + +polypaudio @PACKAGE_VERSION@ + + + + +

polypaudio @PACKAGE_VERSION@

+ +

Copyright 2002-2004 Lennart Poettering <@PACKAGE_BUGREPORT@>

+ + + +

License

+ +

This program is free software; you can redistribute it and/or +modify it under the terms of the GNU 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 +General Public License for more details.

+ +

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

+ +

News

+ + +
Sat Jul 17 2004:

Version 0.1 released

+ +

Overview

+ +

polypaudio is a sound server for Linux and other Unix like +operating systems. It is intended to be an improved drop-in +replacement for the Enlightened Sound +Daemon (ESOUND). In addition to the features ESOUND provides +polypaudio 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 polyplib is quite difficult to use there is +a simplified synchronous API wrapper polyplib-simple +available.

+ +

Status

+ +

Version @PACKAGE_VERSION@ is quite usable. polypaudio does +not yet match all ESOUND features: currently a sample cache and +automatic releasing of unused sound drivers are missing. Have a look on the more extensive TODO list.

+ +

Documentation

+ +

There is some prelimenary documentation available: modules.html, cli.html, daemeon.html.

+ +

Documentation for developing with polypaudio is not yet +available. Read the source, Luke!

+ +

Requirements

+ +

Currently, polypaudio is tested on Linux only. It requires an OSS or ALSA compatible soundcard.

+ +

polypaudio was developed and tested on Debian GNU/Linux +"testing" from July 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.

+ +

polypaudio needs Secret Rabbit Code (aka libsamplerate) and alsa-lib.

+ +

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

+ +

Acknowledgements

+ +

Eric B. Mitchell for writing ESOUND

+ +

Download

+ +

The newest release is always available from @PACKAGE_URL@

+ +

The current release is @PACKAGE_VERSION@

+ +

Get polypaudio's development sources from the Subversion repository. (viewcvs)

+ +

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

+ +
+
Lennart Poettering <@PACKAGE_BUGREPORT@>, July 2004
+
$Id$
+ + + diff --git a/doc/cli.html.in b/doc/cli.html.in new file mode 100644 index 00000000..c67d78db --- /dev/null +++ b/doc/cli.html.in @@ -0,0 +1,152 @@ + + + + +polypaudio: Simple Command Line Language + + + + +

Simple Command Line Language

+ +

polypaudio 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

+ +

modules

+ +

Show all currently loaded modules with their arguments.

+ +

sinks/sources

+ +

Show all currently registered sinks (resp. sources).

+ +

clients

+ +

Show all currently active clients.

+ +

sink_inputs/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

+ +

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

+ +

unload

+ +

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

+ +

Configuration Commands

+ +

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

+ +

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.

+ +

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

+ +
+#!/usr/bin/polaudio -F
+
+# Load audio drivers
+load module-alsa-sink device=plughw:0,0 rate=48000
+load module-alsa-source device=hw:1,0
+
+# Load several protocols
+load module-esound-protocol-tcp
+load module-simple-protocol-tcp
+load module-native-protocol-unix
+load module-cli-protocol-unix
+
+# Load the CLI module (This is similar to passing "-C" on the command line of polypaudio)
+load module-cli
+
+.nofail
+
+# Make some devices default
+sink_default alsa_output
+source_default alsa_input
+
+# Use digital amplification
+sink_volume alsa_output 0x200
+
+ +
+
Lennart Poettering <@PACKAGE_BUGREPORT@>, July 2004
+
$Id$
+ diff --git a/doc/daemon.html.in b/doc/daemon.html.in new file mode 100644 index 00000000..a5d933db --- /dev/null +++ b/doc/daemon.html.in @@ -0,0 +1,51 @@ + + + + +polypaudio: Daemon + + + + +

Daemon

+ +

Command Line Arguments

+ +The polypaudio daemon accepts several command line arguments: + +

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

+

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

+

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

+

-h: Show a quick help.

+ +

Example

+ +

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

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

/etc/polypaudio/polypaudio.pa 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.

+ +
+
Lennart Poettering <@PACKAGE_BUGREPORT@>, July 2004
+
$Id$
+ diff --git a/doc/modules.html.in b/doc/modules.html.in new file mode 100644 index 00000000..6954418f --- /dev/null +++ b/doc/modules.html.in @@ -0,0 +1,191 @@ + + + + +polypaudio: Loadable Modules + + + + + +

Loadable Modules

+ +

The following loadable modules are provided with the polypaudio 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)
+ +

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

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.

+ +

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

This module doesn't accept any arguments.

+ + + + + +

module-cli-protocol-{unix,tcp}

+ +

An implemenation of a simple command line based protocol for +controlling the polypaudio 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.

+ +

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)
socket=(only for -unix) The UNIX socket name (defaults to /tmp/polypaudio/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 polypaudio 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
public=If set to 0 not 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 polypaudio.

+ +

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:

+ + + + +
public=If set to 0 not authentication is required to connect to the service
cookie=Name of the cookie file for authentication purposes
+ + +
+
Lennart Poettering <@PACKAGE_BUGREPORT@>, July 2004
+
$Id$
+ diff --git a/doc/style.css b/doc/style.css new file mode 100644 index 00000000..e54a15a3 --- /dev/null +++ b/doc/style.css @@ -0,0 +1,34 @@ +/* $Id$ */ + +/*** + * This file is part of polypaudio. + * + * polypaudio is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * polypaudio 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 General Public License + * along with polypaudio; 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; margin: 0.5cm; } +a:link, a:visited { color: #900000; } +p { margin-left: 0.5cm; margin-right: 0.5cm; } +div.news-date { margin-left: 0.5cm; font-size: 80%; color: #4f0000; } +p.news-text { margin-left: 1cm; } +h1 { color: #00009F; } +h2 { color: #00009F; } +h3 { color: #00004F; margin-left: 0.5cm; } +ul { margin-left: .5cm; } +ol { margin-left: .5cm; } +pre { margin-left: .5cm; background-color: #f0f0f0; padding: 0.4cm;} +.grey { color: #afafaf; } +table { margin-left: 1cm; border:1px solid lightgrey; padding: 0.2cm; } +td { padding-left:10px; padding-right:10px; } -- cgit