pulseaudio/doc/FAQ.html.in

<?xml version="1.0" encoding="iso-8859-1"?> <!-- -*-html-helper-*- -->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>polypaudio: FAQ</title>
<link rel="stylesheet" type="text/css" href="style.css" />
</head>

<body>


<h1>Frequently Asked Questions</h1>

<ol>
  <li><p><b>How does Polypaudio compare with ESOUND/aRts/NAS?</b></p>

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

  <li><p><b>What about ESOUND compatibility?</b></p>
  <p>Polypaudio 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
  <tt>esdcat</tt>).</p>
  </li>

  <li><p><b>Is Polypaudio a GNOME program?</b></p>
  <p>No, Polypaudio 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 writen with
  gtkmm, i.e. require both GLIB and GTK.</p></li>

  <li><p><b>Can I integrate Polypaudio in my GLIB/GTK/GNOME application?</b></p>
  <p>Yes! Polypaudio comes with a GLIB main loop adapter. You can embed
  both the client library and the daemon (!) into your GLIB based
  application.</p></li>

  <li><p><b>Can I integrate Polypaudio in my Qt/KDE application?</b></p>
  <p>Yes! Polypaudio uses a main loop abstraction layer that allows you
  to integrate Polypaudio in any program that supports main
  loops. Unfortunately there is no adapter for Qt publicly available yet.</p></li>

  <li><p><b>I want to write a new driver for Polypaudio, are there any docs?</b></p>
  <p>Currently, only the client API is documented with doxygen. Read
  the source and base your work on a simple module like
  <tt>module-pipe-sink</tt>.</p></li>

  <li><p><b>What about compatibility with NAS?</b></p>
  <p>Is not available (yet?). It is doable, but noone has implemented it yet.</p></li>

  <li><p><b>What about compatibility with aRts?</b></p>
  <p>Is not available. Since aRts is as synthesizer application you'd have to
  reimplement very much code for Polypaudio. It should be easy to
  implement limited support for <tt>libartsc</tt> based
  applications. Noone has done this yet. It is probably a better idea to
  run <tt>arts</tt> on top of Polypaudio (through a polypaudio driver
  for aRts, which nobody has written yet). Another solution would be to
  embed Polypaudio in the aRts process.</p></li>

  <li><p><b>I often hear noises when playing back with Polypaudio, what can I do?</b></p>
  <p>There are to possible solutions: run polypaudio with argument
<tt>--high-priority=1</tt> and make yourself member of the group
<tt>realtime</tt>, or increase the fragment sizes of the audio
  drivers. The former will allow Polypaudio to activate
  <tt>SCHED_FIFO</tt> high priority scheduling (root rights are dropped
  immediately after this) Keep in mind that this is a potential security hole!</p></li>

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

  <p>Polypaudio activates <tt>SCHED_FIFO</tt> scheduling if the user
passes <tt>--high-priority=1</tt>. 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, polypaudio
tries its best to minimize the security threat: immediately after
startup polypaudio drops all capabilities except
<tt>CAP_SYS_NICE</tt> (At least on systems that support it, like Linux; see <tt>man 7
capabilities</tt> for more information). If the calling user is not a
member of the group <tt>realtime</tt> (which is required to have a GID
< 1000), root rights are dropped immediately. This means, you can
install polypaudio SUID root, but only a subset of your users (the
members of the group <tt>realtime</tt>) may make use of realtime
scheduling. Keep in mind that these users might load their own binary
modules into the polypaudio 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.</p></li>
  
  <li><p><b>I want to run polypaudio only when it is needed, how do I do this?</b></p>

  <p>Set <tt>autospawn = yes</tt> in <tt>client.conf</tt>. That
configuration file may be found either in <tt>/etc/polypaudio/</tt> or
in <tt>~/.polypaudio/</tt>.</p></li>

  <li><p><b>How do I list all polypaudio modules installed?</b></p>

   <p><tt>polypaudio --dump-modules</tt></p>

   <p>Add <tt>-v</tt> for terse usage instructions.</p>

<li><p><b>How do I use polypaudio over the network?</b></p>

<p>Just set <tt>$POLYP_SERVER</tt> to the host name of the polypaudio server.</p>

<li><p><b>Is polypaudio capable of providing synchronized audio playback over the network for movie players like <tt>mplayer</tt>?</b></p>

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

   <li><p><b>What environment variables does polypaudio care about?</b></p>

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

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


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

<p>A brilliant guy named Lennart Poettering once wrote a nifty tool
for that purpose: <a
href="http://0pointer.de/lennart/projects/bidilink/">bidilink</a>. To
connect to a running polypaudio daemon try using the following commands:</p>

<pre>killall -USR2 polypaudio
bidilink unix-client:/tmp/polypaudio/cli</pre>

<p><i>BTW: Someone should package that great tool for Debian!</i></p>


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

<li><p><b>How do the polypaudio libraries decide where to connect to?</b></p>
<p>The following rule applies:</p>
<ol>
  <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>
  <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>
  <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>
  <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>
  <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>
  <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>
  <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>
  <li>The connection fails.</li>
</ol>
</li>

<li><p><b>Why the heck does libpolyp link against libX11?</b></p>
<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>

</ol>

<hr/>
<address class="grey">Lennart Poettering &lt;@PACKAGE_BUGREPORT@&gt;, September 2004</address>
<div class="grey"><i>$Id$</i></div>
</body> </html>
documentation update git-svn-id: file:///home/lennart/svn/public/pulseaudio/trunk@185 fefdeb5f-60dc-0310-8127-8f9354f1896f 2004-09-07 22:40:43 +00:00			`<?xml version="1.0" encoding="iso-8859-1"?> <!-- --html-helper-- -->`
			`<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">`
			`<html xmlns="http://www.w3.org/1999/xhtml">`
			`<head>`
			`<title>polypaudio: FAQ</title>`
			`<link rel="stylesheet" type="text/css" href="style.css" />`
			`</head>`

			`<body>`


			`<h1>Frequently Asked Questions</h1>`

			`<ol>`
			`<li><p><b>How does Polypaudio compare with ESOUND/aRts/NAS?</b></p>`

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

			`<li><p><b>What about ESOUND compatibility?</b></p>`
			`<p>Polypaudio 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`
			`<tt>esdcat</tt>).</p>`
			`</li>`

			`<li><p><b>Is Polypaudio a GNOME program?</b></p>`
			`<p>No, Polypaudio 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 writen with`
			`gtkmm, i.e. require both GLIB and GTK.</p></li>`

			`<li><p><b>Can I integrate Polypaudio in my GLIB/GTK/GNOME application?</b></p>`
			`<p>Yes! Polypaudio comes with a GLIB main loop adapter. You can embed`
			`both the client library and the daemon (!) into your GLIB based`
			`application.</p></li>`

			`<li><p><b>Can I integrate Polypaudio in my Qt/KDE application?</b></p>`
			`<p>Yes! Polypaudio uses a main loop abstraction layer that allows you`
			`to integrate Polypaudio in any program that supports main`
			`loops. Unfortunately there is no adapter for Qt publicly available yet.</p></li>`

			`<li><p><b>I want to write a new driver for Polypaudio, are there any docs?</b></p>`
			`<p>Currently, only the client API is documented with doxygen. Read`
			`the source and base your work on a simple module like`
			`<tt>module-pipe-sink</tt>.</p></li>`

			`<li><p><b>What about compatibility with NAS?</b></p>`
			`<p>Is not available (yet?). It is doable, but noone has implemented it yet.</p></li>`

			`<li><p><b>What about compatibility with aRts?</b></p>`
			`<p>Is not available. Since aRts is as synthesizer application you'd have to`
			`reimplement very much code for Polypaudio. It should be easy to`
			`implement limited support for <tt>libartsc</tt> based`
			`applications. Noone has done this yet. It is probably a better idea to`
			`run <tt>arts</tt> on top of Polypaudio (through a polypaudio driver`
			`for aRts, which nobody has written yet). Another solution would be to`
			`embed Polypaudio in the aRts process.</p></li>`

			`<li><p><b>I often hear noises when playing back with Polypaudio, what can I do?</b></p>`
bump version number and update documentation git-svn-id: file:///home/lennart/svn/public/pulseaudio/trunk@239 fefdeb5f-60dc-0310-8127-8f9354f1896f 2004-09-23 23:26:15 +00:00			`<p>There are to possible solutions: run polypaudio with argument`
			`<tt>--high-priority=1</tt> and make yourself member of the group`
			`<tt>realtime</tt>, or increase the fragment sizes of the audio`
documentation update git-svn-id: file:///home/lennart/svn/public/pulseaudio/trunk@185 fefdeb5f-60dc-0310-8127-8f9354f1896f 2004-09-07 22:40:43 +00:00			`drivers. The former will allow Polypaudio to activate`
			`<tt>SCHED_FIFO</tt> high priority scheduling (root rights are dropped`
bump version number and update documentation git-svn-id: file:///home/lennart/svn/public/pulseaudio/trunk@239 fefdeb5f-60dc-0310-8127-8f9354f1896f 2004-09-23 23:26:15 +00:00			`immediately after this) Keep in mind that this is a potential security hole!</p></li>`

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

			`<p>Polypaudio activates <tt>SCHED_FIFO</tt> scheduling if the user`
			`passes <tt>--high-priority=1</tt>. 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, polypaudio`
			`tries its best to minimize the security threat: immediately after`
			`startup polypaudio drops all capabilities except`
			`<tt>CAP_SYS_NICE</tt> (At least on systems that support it, like Linux; see <tt>man 7`
			`capabilities</tt> for more information). If the calling user is not a`
			`member of the group <tt>realtime</tt> (which is required to have a GID`
			`< 1000), root rights are dropped immediately. This means, you can`
			`install polypaudio SUID root, but only a subset of your users (the`
			`members of the group <tt>realtime</tt>) may make use of realtime`
			`scheduling. Keep in mind that these users might load their own binary`
			`modules into the polypaudio 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.</p></li>`

			`<li><p><b>I want to run polypaudio only when it is needed, how do I do this?</b></p>`
documentation update git-svn-id: file:///home/lennart/svn/public/pulseaudio/trunk@225 fefdeb5f-60dc-0310-8127-8f9354f1896f 2004-09-20 20:52:35 +00:00
			`<p>Set <tt>autospawn = yes</tt> in <tt>client.conf</tt>. That`
			`configuration file may be found either in <tt>/etc/polypaudio/</tt> or`
			`in <tt>~/.polypaudio/</tt>.</p></li>`

			`<li><p><b>How do I list all polypaudio modules installed?</b></p>`

			`<p><tt>polypaudio --dump-modules</tt></p>`

			`<p>Add <tt>-v</tt> for terse usage instructions.</p>`

bump version number and update documentation git-svn-id: file:///home/lennart/svn/public/pulseaudio/trunk@239 fefdeb5f-60dc-0310-8127-8f9354f1896f 2004-09-23 23:26:15 +00:00			`<li><p><b>How do I use polypaudio over the network?</b></p>`

			`<p>Just set <tt>$POLYP_SERVER</tt> to the host name of the polypaudio server.</p>`

			`<li><p><b>Is polypaudio capable of providing synchronized audio playback over the network for movie players like <tt>mplayer</tt>?</b></p>`

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

			`<li><p><b>What environment variables does polypaudio care about?</b></p>`
documentation update git-svn-id: file:///home/lennart/svn/public/pulseaudio/trunk@225 fefdeb5f-60dc-0310-8127-8f9354f1896f 2004-09-20 20:52:35 +00:00
			`<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>`

			`<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>`
bump version number and update documentation git-svn-id: file:///home/lennart/svn/public/pulseaudio/trunk@239 fefdeb5f-60dc-0310-8127-8f9354f1896f 2004-09-23 23:26:15 +00:00

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

			`<p>A brilliant guy named Lennart Poettering once wrote a nifty tool`
			`for that purpose: <a`
			`href="http://0pointer.de/lennart/projects/bidilink/">bidilink</a>. To`
			`connect to a running polypaudio daemon try using the following commands:</p>`

			`<pre>killall -USR2 polypaudio`
			`bidilink unix-client:/tmp/polypaudio/cli</pre>`

Documentation updates git-svn-id: file:///home/lennart/svn/public/pulseaudio/trunk@310 fefdeb5f-60dc-0310-8127-8f9354f1896f 2004-11-21 22:07:47 +00:00			`<p><i>BTW: Someone should package that great tool for Debian!</i></p>`
implemented pax11publish.c git-svn-id: file:///home/lennart/svn/public/pulseaudio/trunk@275 fefdeb5f-60dc-0310-8127-8f9354f1896f 2004-11-08 23:48:19 +00:00

Documentation updates git-svn-id: file:///home/lennart/svn/public/pulseaudio/trunk@310 fefdeb5f-60dc-0310-8127-8f9354f1896f 2004-11-21 22:07:47 +00:00			`<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>`
			`</li>`
implemented pax11publish.c git-svn-id: file:///home/lennart/svn/public/pulseaudio/trunk@275 fefdeb5f-60dc-0310-8127-8f9354f1896f 2004-11-08 23:48:19 +00:00
			`<li><p><b>How do the polypaudio libraries decide where to connect to?</b></p>`
			`<p>The following rule applies:</p>`
			`<ol>`
			`<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>`
			`<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>`
			`<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>`
			`<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>`
			`<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>`
			`<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>`
			`<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>`
			`<li>The connection fails.</li>`
			`</ol>`
bump version number and update documentation git-svn-id: file:///home/lennart/svn/public/pulseaudio/trunk@239 fefdeb5f-60dc-0310-8127-8f9354f1896f 2004-09-23 23:26:15 +00:00			`</li>`

Documentation updates git-svn-id: file:///home/lennart/svn/public/pulseaudio/trunk@310 fefdeb5f-60dc-0310-8127-8f9354f1896f 2004-11-21 22:07:47 +00:00			`<li><p><b>Why the heck does libpolyp link against libX11?</b></p>`
			`<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>`

documentation update git-svn-id: file:///home/lennart/svn/public/pulseaudio/trunk@185 fefdeb5f-60dc-0310-8127-8f9354f1896f 2004-09-07 22:40:43 +00:00			`</ol>`

			`<hr/>`
			`<address class="grey">Lennart Poettering <@PACKAGE_BUGREPORT@>, September 2004</address>`
			`<div class="grey"><i>$Id$</i></div>`
			`</body> </html>`