code.delx.au - pulseaudio/blob - doc/README.html.in

   1 <?xml version="1.0" encoding="iso-8859-1"?> <!-- -*-html-helper-*- -->
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4
   5 <head>
   6 <title>polypaudio @PACKAGE_VERSION@</title>
   7 <link rel="stylesheet" type="text/css" href="style.css" />
   8 </head>
   9
  10 <body>
  11 <h1><a name="top">polypaudio @PACKAGE_VERSION@</a></h1>
  12
  13 <p><i>Copyright 2004 Lennart Poettering &lt;@PACKAGE_BUGREPORT@&gt;</i></p>
  14
  15 <ul class="toc">
  16     <li><a href="#license">License</a></li>
  17     <li><a href="#news">News</a></li>
  18     <li><a href="#overview">Overview</a></li>
  19     <li><a href="#status">Status</a></li>
  20     <li><a href="#documentation">Documentation</a></li>
  21     <li><a href="#requirements">Requirements</a></li>
  22     <li><a href="#installation">Installation</a></li>
  23     <li><a href="#acks">Acknowledgements</a></li>
  24     <li><a href="#download">Download</a></li>
  25 </ul>
  26
  27 <h2><a name="license">License</a></h2>
  28
  29 <p>This program is free software; you can redistribute it and/or
  30 modify it under the terms of the GNU General Public License as
  31 published by the Free Software Foundation; either version 2 of the
  32 License, or (at your option) any later version.</p>
  33
  34 <p>This program is distributed in the hope that it will be useful, but
  35 WITHOUT ANY WARRANTY; without even the implied warranty of
  36 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  37 General Public License for more details.</p>
  38
  39 <p>You should have received a copy of the GNU General Public License
  40 along with this program; if not, write to the Free Software
  41 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.</p>
  42
  43 <p><i>Exception: The client libraries are licensed under LGPL, the Lesser GNU General Plublic License.</i></p>
  44
  45 <h2><a name="news">News</a></h2>
  46
  47 <div class="news-date">Fri Aug 27 2004: </div> <p class="news-text"><a
  48 href="@PACKAGE_URL@polypaudio-0.3.tar.gz">Version 0.3</a> released;
  49 changes include: support for both glib 2.0 and glib 1.2, future cancellation, API updates, many fixes; relicense client library to LGPL.</p>
  50
  51 <div class="news-date">Fri Aug 20 2004: </div> <p class="news-text"><a
  52 href="@PACKAGE_URL@polypaudio-0.2.tar.gz">Version 0.2</a> released;
  53 changes include: added sample cache, introspection API, client API
  54 documentation, module autoloading, glib support, a module for intercepting X11 bell events, and much more.</p>
  55
  56 <div class="news-date">Sat Jul 17 2004: </div> <p class="news-text"><a
  57 href="@PACKAGE_URL@polypaudio-0.1.tar.gz">Version 0.1</a> released</p>
  58
  59 <h2><a name="overview">Overview</a></h2>
  60
  61 <p><tt>polypaudio</tt> is a sound server for Linux and other Unix like
  62 operating systems. It is intended to be an improved drop-in
  63 replacement for the <a
  64 href="http://www.tux.org/~ricdude/apps.html">Enlightened Sound
  65 Daemon</a> (ESOUND). In addition to the features ESOUND provides
  66 <tt>polypaudio</tt> has:</p>
  67
  68 <ul>
  69   <li>Extensible plugin architecture (by loading dynamic loadable modules with <tt>dlopen()</tt>)</li>
  70   <li>Support for more than one sink/source</li>
  71   <li>Better low latency behaviour</li>
  72   <li>Embedabble into other software (the core is available as C library)</li>
  73   <li>Completely asynchronous C API</li>
  74   <li>Simple command line interface for reconfiguring the daemon while running</li>
  75   <li>Flexible, implicit sample type conversion and resampling</li>
  76   <li>"Zero-Copy" architecture</li>
  77   <li>Module autoloading</li>
  78 </ul>
  79
  80 <p>Both the core and the client API are completely asynchronous making
  81 use of a simple main loop abstraction layer. This allows easy
  82 integration with asynchronous applications using the
  83 <tt>glib</tt>/<tt>gtk</tt> mainloop. Since the asynchronous API
  84 available through <tt>polyplib</tt> is quite difficult to use there is
  85 a simplified synchronous API wrapper <tt>polyplib-simple</tt>
  86 available. A simple main loop implementation is available as well.</p>
  87
  88 <p><tt>polypaudio</tt> is the successor of my previous, ill-fated
  89 attempt to write a sound server <a
  90 href="http://asd.sf.net/">asd</a>.</p>
  91
  92 <p>A GTK GUI manager application for polypaudio is the <a
  93 href="http://0pointer.de/lennart/projects/paman/">Polypaudio Manager</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>
  94
  95 <h2><a name="status">Status</a></h2>
  96
  97 <p>Version @PACKAGE_VERSION@ is quite usable. It matches and supersedes ESOUND's feature set in nearly all areas.</p>
  98
  99 <p><b>Warning:</b> polypaudio's client API and protocol are not stable
 100 yet. The client interface is still a moving target and changes from
 101 release to release. The client API's library version number is currently fixed to <tt>0.0.0</tt>.</p>
 102
 103 <h2><a name="documentation">Documentation</a></h2>
 104
 105 <p>There is some preliminary documentation available: <a
 106 href="modules.html"><tt>modules.html</tt></a>, <a
 107 href="cli.html"><tt>cli.html</tt></a>, <a
 108 href="daemon.html"><tt>daemon.html</tt></a>.</p>
 109
 110 <h3>First Steps</h3>
 111
 112 <p>Simply start the polypaudio daemon with the argument <tt>-C</tt></p>
 113
 114 <pre>polypaudio -C</pre>
 115
 116 <p>This will present you a screen like this:</p>
 117
 118 <pre>Welcome to polypaudio! Use "help" for usage information.
 119 &gt;&gt;&gt; </pre>
 120
 121 <p>Now you can issue CLI commands as described in <a
 122 href="cli.html"><tt>cli.html</tt></a>. Another way to start
 123 <tt>polypaudio</tt> is by specifying a configuration script like that one included in the distribution on the
 124 command line :</p>
 125
 126 <pre>polypaudio -F polypaudio.pa</pre>
 127
 128 <p>This will load some drivers and protocols automatically.</p>
 129
 130 <h3>Developing polypaudio Clients</h3>
 131
 132 <p>You may browse the <a href="http://www.doxygen.org/">Doxygen</a> generated <a
 133 href="http://0pointer.de/lennart/projects/polypaudio/doxygen/">programing
 134 documentation</a> for the client API. (Run <tt>make doxygen</tt> to generate this documentation from the source tree)</p>
 135
 136 <h3>Developing polypaudio Modules</h3>
 137
 138 <p>There are several reasons for writing loadable modules for polypaudio:</p>
 139
 140 <ul>
 141   <li>Device driver support in addition to ALSA/OSS</li>
 142   <li>Protocol support beyond ESOUND's protocol and the native protocol. (such as NAS or a subset of aRts)</li>
 143   <li>New programming interfaces such as XMLRPC or DBUS for controlling the daemon.</li>
 144   <li>Hooking audio event sources directly into polypaudio (similar to <tt>module-x11-bell</tt>)</li>
 145   <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>
 146 </ul>
 147
 148 <p>There is currently no documentation how to write loadable modules
 149 for polypaudio. <i>Read the source, Luke!</i> If you are interested in
 150 writing new modules feel free to contact the author in case you have any
 151 questions.</p>
 152
 153 <h2><a name="requirements">Requirements</a></h2>
 154
 155 <p>Currently, <tt>polypaudio</tt> is tested on Linux only. It requires an OSS or ALSA compatible soundcard.</p>
 156
 157 <p><tt>polypaudio</tt> was developed and tested on Debian GNU/Linux
 158 "testing" from July 2004, it should work on most other Linux
 159 distributions (and maybe Unix versions) since it uses GNU autoconf and
 160 GNU libtool for source code configuration and shared library
 161 management.</p>
 162
 163 <p><tt>polypaudio</tt> needs <a
 164 href="http://www.mega-nerd.com/SRC/">Secret Rabbit Code (aka
 165 <tt>libsamplerate</tt>)</a>, <a href="http://www.mega-nerd.com/libsndfile"><tt>libsndfile</tt></a>, <a
 166 href="http://www.alsa-project.org/">alsa-lib</a> and <a href="http://www.gtk.org/">GLIB</a>. (The latter is required for building the GLIB main loop integration module only.)</p>
 167
 168 <h2><a name="installation">Installation</a></h2>
 169
 170 <p>As this package is made with the GNU autotools you should run
 171 <tt>./configure</tt> inside the distribution directory for configuring
 172 the source tree. After that you should run <tt>make</tt> for
 173 compilation and <tt>make install</tt> (as root) for installation of
 174 <tt>polypaudio</tt>.</p>
 175
 176 <h2><a name="acks">Acknowledgements</a></h2>
 177
 178 <p>Eric B. Mitchell for writing ESOUND</p>
 179
 180 <h2><a name="download">Download</a></h2>
 181
 182 <p>The newest release is always available from <a href="@PACKAGE_URL@">@PACKAGE_URL@</a></p>
 183
 184 <p>The current release is <a href="@PACKAGE_URL@polypaudio-@PACKAGE_VERSION@.tar.gz">@PACKAGE_VERSION@</a></p>
 185
 186 <p>Get <tt>polypaudio</tt>'s development sources from the <a href="http://subversion.tigris.org/">Subversion</a> <a href="https://seth.intheinter.net:8081/svn/polypaudio/">repository</a>. (<a href="http://0pointer.de/cgi-bin/viewcvs.cgi/?root=polypaudio">viewcvs</a>)</p>
 187
 188 <p>If you want to be notified whenever I release a new version of this software use the subscription feature of <a href="http://freshmeat.net/projects/polypaudio/">Freshmeat</a>.</p>
 189
 190 <hr/>
 191 <address class="grey">Lennart Poettering &lt;@PACKAGE_BUGREPORT@&gt;, August 2004</address>
 192 <div class="grey"><i>$Id$</i></div>
 193
 194 </body>
 195 </html>