code.delx.au - pulseaudio/blob - doc/FAQ.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 <head>
   5 <title>polypaudio: FAQ</title>
   6 <link rel="stylesheet" type="text/css" href="style.css" />
   7 </head>
   8
   9 <body>
  10
  11
  12 <h1>Frequently Asked Questions</h1>
  13
  14 <ol>
  15   <li><p><b>How does Polypaudio compare with ESOUND/aRts/NAS?</b></p>
  16
  17   <p>Polypaudio is sound daemon similar to ESOUND and NAS, but much more
  18   powerful. aRts is a realtime-synthesizer-cum-sound-server, i.e. it
  19   does much more than Polypaudio. However, I believe that Polypaudio
  20   does what it does much better than any other free sound server.</p>
  21   </li>
  22
  23   <li><p><b>What about ESOUND compatibility?</b></p>
  24   <p>Polypaudio is a drop in replacement for ESOUND. That means: you can
  25   load a esound compatibility module which implements an ESOUND
  26   compatible protocol which allows you to use most of the classic ESOUND
  27   compatible programs (including the command line programs like
  28   <tt>esdcat</tt>).</p>
  29   </li>
  30
  31   <li><p><b>Is Polypaudio a GNOME program?</b></p>
  32   <p>No, Polypaudio has no dependency on GNOME/GTK/GLIB. All it requires
  33   is a UNIX-like operating system and very few dependency
  34   libraries. However, the accompanying GUI tools are writen with
  35   gtkmm, i.e. require both GLIB and GTK.</p></li>
  36
  37   <li><p><b>Can I integrate Polypaudio in my GLIB/GTK/GNOME application?</b></p>
  38   <p>Yes! Polypaudio comes with a GLIB main loop adapter. You can embed
  39   both the client library and the daemon (!) into your GLIB based
  40   application.</p></li>
  41
  42   <li><p><b>Can I integrate Polypaudio in my Qt/KDE application?</b></p>
  43   <p>Yes! Polypaudio uses a main loop abstraction layer that allows you
  44   to integrate Polypaudio in any program that supports main
  45   loops. Unfortunately there is no adapter for Qt publicly available yet.</p></li>
  46
  47   <li><p><b>I want to write a new driver for Polypaudio, are there any docs?</b></p>
  48   <p>Currently, only the client API is documented with doxygen. Read
  49   the source and base your work on a simple module like
  50   <tt>module-pipe-sink</tt>.</p></li>
  51
  52   <li><p><b>What about compatibility with NAS?</b></p>
  53   <p>Is not available (yet?). It is doable, but noone has implemented it yet.</p></li>
  54
  55   <li><p><b>What about compatibility with aRts?</b></p>
  56   <p>Is not available. Since aRts is as synthesizer application you'd have to
  57   reimplement very much code for Polypaudio. It should be easy to
  58   implement limited support for <tt>libartsc</tt> based
  59   applications. Noone has done this yet. It is probably a better idea to
  60   run <tt>arts</tt> on top of Polypaudio (through a polypaudio driver
  61   for aRts, which nobody has written yet). Another solution would be to
  62   embed Polypaudio in the aRts process.</p></li>
  63
  64   <li><p><b>I often hear noises when playing back with Polypaudio, what can I do?</b></p>
  65   <p>There are to possible solutions: run polypaudio with argument
  66 <tt>--high-priority=1</tt> and make yourself member of the group
  67 <tt>realtime</tt>, or increase the fragment sizes of the audio
  68   drivers. The former will allow Polypaudio to activate
  69   <tt>SCHED_FIFO</tt> high priority scheduling (root rights are dropped
  70   immediately after this) Keep in mind that this is a potential security hole!</p></li>
  71
  72    <li><p><b>The <tt>polypaudio</tt>  executable is installed SUID root by default. Why this? Isn't this a potential security hole?</b></p>
  73
  74   <p>Polypaudio activates <tt>SCHED_FIFO</tt> scheduling if the user
  75 passes <tt>--high-priority=1</tt>. This will only succeed when
  76 executed as root, therefore the binary is marked SUID root by
  77 default. Yes, this is a potential security hole. However, polypaudio
  78 tries its best to minimize the security threat: immediately after
  79 startup polypaudio drops all capabilities except
  80 <tt>CAP_SYS_NICE</tt> (At least on systems that support it, like Linux; see <tt>man 7
  81 capabilities</tt> for more information). If the calling user is not a
  82 member of the group <tt>realtime</tt> (which is required to have a GID
  83 < 1000), root rights are dropped immediately. This means, you can
  84 install polypaudio SUID root, but only a subset of your users (the
  85 members of the group <tt>realtime</tt>) may make use of realtime
  86 scheduling. Keep in mind that these users might load their own binary
  87 modules into the polypaudio daemon which may freeze the machine. The
  88 daemon has a minimal protection against CPU hogging (the daemon is
  89 killed after hogging more than 70% CPU for 5 seconds), but this may
  90 be circumvented easily by evildoers.</p></li>
  91
  92   <li><p><b>I want to run polypaudio only when it is needed, how do I do this?</b></p>
  93
  94   <p>Set <tt>autospawn = yes</tt> in <tt>client.conf</tt>. That
  95 configuration file may be found either in <tt>/etc/polypaudio/</tt> or
  96 in <tt>~/.polypaudio/</tt>.</p></li>
  97
  98   <li><p><b>How do I list all polypaudio modules installed?</b></p>
  99
 100    <p><tt>polypaudio --dump-modules</tt></p>
 101
 102    <p>Add <tt>-v</tt> for terse usage instructions.</p>
 103
 104 <li><p><b>How do I use polypaudio over the network?</b></p>
 105
 106 <p>Just set <tt>$POLYP_SERVER</tt> to the host name of the polypaudio server.</p>
 107
 108 <li><p><b>Is polypaudio capable of providing synchronized audio playback over the network for movie players like <tt>mplayer</tt>?</b></p>
 109
 110 <p>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.</p>
 111
 112    <li><p><b>What environment variables does polypaudio care about?</b></p>
 113
 114 <p>The client honors: <tt>POLYP_SINK</tt> (default sink to connect to), <tt>POLYP_SOURCE</tt> (default source to connect to), <tt>POLYP_SERVER</tt> (default server to connect to, like <tt>ESPEAKER</tt>), <tt>POLYP_BINARY</tt> (the binary to start when autospawning a daemon), <tt>POLYP_CLIENTCONFIG</tt> (path to the client configuration file).</p>
 115
 116 <p>The daemon honors: <tt>POLYP_SCRIPT</tt> (default CLI script file run after startup), <tt>POLYP_CONFIG</tt> (default daemon configuration file), <tt>POLYP_DLPATH</tt> (colon separated list of paths where to look for modules)</p></li>
 117
 118
 119 <li><p><b>I saw that SIGUSR2 provokes loading of the module <tt>module-cli-protocol-unix</tt>. But how do I make use of that?</b></p>
 120
 121 <p>A brilliant guy named Lennart Poettering once wrote a nifty tool
 122 for that purpose: <a
 123 href="http://0pointer.de/lennart/projects/bidilink/">bidilink</a>. To
 124 connect to a running polypaudio daemon try using the following commands:</p>
 125
 126 <pre>killall -USR2 polypaudio
 127 bidilink unix-client:/tmp/polypaudio/cli</pre>
 128
 129 <p><i>BTW: Someone should package that great tool for Debian!</i></p>
 130
 131 <p><b>New:</b> There's now a tool <tt>pacmd</tt> that automates sending SIGUSR2 to the daemon and running a bidilink like tool for you.</p>
 132 </li>
 133
 134 <li><p><b>How do the polypaudio libraries decide where to connect to?</b></p>
 135 <p>The following rule applies:</p>
 136 <ol>
 137   <li>If the the application using the library specifies a server to connect to it is used. If the connection fails, the library fails too.</li>
 138   <li>If the environment variable <tt>POLYP_SERVER</tt> is defined the library connects to that server. If the connection fails, the library fails too.</li>
 139   <li>If <tt>$DISPLAY</tt> is set, the library tries to connect to that server and looks for the root window property <tt>POYLP_SERVER</tt> for the host to connect to. If <tt>POLYP_COOKIE</tt> is set it is used as authentication cookie.</li>
 140   <li>If the client configuration file (<tt>~/.polypaudio/client.conf</tt> or <tt>/etc/polypaudio/client.conf</tt>) sets the server address, the library connects to that server. If the connection fails, the library fails too.</li>
 141   <li>The library tries to connect to the default local UNIX socket for polypaudio servers. If the connection fails, it proceeds with the next item.</li>
 142   <li>The library tries to connect to the default local TCP socket for polypaudio servers. If the connection fails, it proceeds with the next item.</li>
 143   <li>If <tt>$DISPLAY</tt> 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.</li>
 144   <li>The connection fails.</li>
 145 </ol>
 146 </li>
 147
 148 <li><p><b>Why the heck does libpolyp link against libX11?</b></p>
 149 <p>The Polypaudio client libraries look for some X11 root window properties for the credentials of the Polypaudio server to access. You may compile Polypaudio without X11 for disabling this.</p></li>
 150
 151 </ol>
 152
 153 <hr/>
 154 <address class="grey">Lennart Poettering &lt;@PACKAGE_BUGREPORT@&gt;, April 2006</address>
 155 <div class="grey"><i>$Id$</i></div>
 156 </body> </html>