Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdemultimedia@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 1112 insertions, 0 deletions

diff --git a/doc/artsbuilder/faq.docbook b/doc/artsbuilder/faq.docbook
new file mode 100644
index 00000000..c5b111ec
--- /dev/null
+++ b/doc/artsbuilder/faq.docbook
@@ -0,0 +1,1112 @@
+<!-- <?xml version="1.0" ?>
+<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd">
+To validate or process this file as a standalone document, uncomment
+this prolog. Be sure to comment it out again when you are done -->
+<chapter id="faq">
+<title>Questions and answers</title>
+
+<para>
+This section answers some frequently asked questions about &arts;.
+</para>
+
+<qandaset id="faq-general">
+<title>General Questions</title>
+
+<qandaentry>
+<question>
+<para>
+Does &kde; support my sound card for audio output?
+</para>
+</question>
+
+<answer>
+<para>
+&kde; uses &arts; to play sound, and &arts; uses the &Linux; kernel
+sound drivers, either <acronym>OSS</acronym> or <acronym>ALSA</acronym>
+(using <acronym>OSS</acronym> emulation). If your sound card is
+supported by either <acronym>ALSA</acronym> or <acronym>OSS</acronym>
+and properly configured (&ie; any other &Linux; application can output
+sound), it will work. There are however some problems with some specific
+hardware, please read the <link linkend="faq-hardware-specific">section
+for hardware specific problems</link> if you're having problems with artsd
+on your machine.
+</para>
+<para>
+Meanwhile also support for various other platforms has been added. Here is
+a complete list of how the most recent version of &arts; can play sound. If
+you have an unsupported platform, please consider porting &arts; to your
+platform.
+</para>
+
+<informaltable>
+<tgroup cols="2">
+<thead>
+<row>
+<entry>&arts; audio I/O method</entry>
+<entry>Comment</entry>
+</row>
+</thead>
+
+<tbody>
+<row>
+<entry>paud</entry>
+<entry>Support for AIX Personal Audio Device</entry>
+</row>
+
+<row>
+<entry>alsa</entry>
+<entry>Linux ALSA-0.5 and ALSA-0.9 drivers</entry>
+</row>
+
+<row>
+<entry>libaudioio</entry>
+<entry>Support for generic LibAudioIO library which works on Solaris</entry>
+</row>
+
+<row>
+<entry>nas</entry>
+<entry>NAS sound server, useful for X Terminals with NAS support</entry>
+</row>
+
+<row>
+<entry>null</entry>
+<entry>Null audio device, discards sound silently</entry>
+</row>
+
+<row>
+<entry>oss</entry>
+<entry>OSS (Open Sound System) support (works on Linux, various BSDs and
+       other platforms with OSS drivers installed)</entry>
+</row>
+
+<row>
+<entry>toss</entry>
+<entry>Threaded OSS support, which works better in some cases where the
+       standard OSS support doesn't work well</entry>
+</row>
+
+<row>
+<entry>sgi</entry>
+<entry>SGI Direct Media support for IRIX</entry>
+</row>
+
+<row>
+<entry>sun</entry>
+<entry>Solaris support</entry>
+</row>
+
+</tbody>
+</tgroup>
+</informaltable>
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question>
+<para>
+I can't play <literal role="extension">wav</literal> files with &artsd;!
+</para>
+</question>
+
+<answer>
+<para>
+Check that &artsd; is linked to <filename>libaudiofile</filename>
+(<userinput><command>ldd</command>
+<parameter>artsd</parameter></userinput>). If it isn't, download
+kdesupport, recompile everything, and it will work.
+</para>
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question>
+<para>
+I hear sound when logged in as <systemitem
+class="username">root</systemitem> but no other users have sound!
+</para>
+</question>
+
+<answer>
+<para>
+The permissions of the file <filename
+class="devicefile">/dev/dsp</filename> affect which users will have
+sound. To allow everyone to use it, do this:
+</para>
+
+<procedure>
+<step>
+<para>
+Log in as <systemitem class="username">root</systemitem>.
+</para>
+</step>
+
+<step>
+<para>
+Open a &konqueror; window.
+</para>
+</step>
+
+<step>
+<para>
+Go into the <filename class="directory">/dev</filename> folder.
+</para>
+</step>
+
+<step>
+<para>
+Click on the file <filename>dsp</filename> with the
+<mousebutton>right</mousebutton> mouse button, and choose properties.
+</para>
+</step>
+
+<step>
+<para>
+Click on the <guilabel>Permissions</guilabel> tab.
+</para>
+</step>
+
+<step>
+<para>
+Check the <guilabel>Read</guilabel> and <guilabel>Write</guilabel> check
+boxes in all sections.
+</para>
+</step>
+
+<step>
+<para>
+Click on <guibutton>OK</guibutton>.
+</para>
+</step>
+</procedure>
+
+<para>
+You can achieve the same effect in a terminal window using the command
+<userinput><command>chmod</command> <option>666</option>
+<parameter>/dev/dsp</parameter></userinput>.
+</para>
+
+<para>
+For restricting access to sound to specific users, you can use group
+permissions. On some &Linux; distributions, for instance Debian/Potato,
+<filename class="devicefile">/dev/dsp</filename> is already owned by a
+group called <systemitem class="groupname">audio</systemitem>, so all
+you need to do is add the users to this group.
+</para>
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question>
+<para>
+This helps for &artsd;, but what about &kmix;, &kmid;, &kscd;,&etc;?
+</para>
+</question>
+<answer>
+
+<para>
+There are various other devices which provide functionality accessed by
+multimedia applications. You can treat them in the same way, either by
+making them accessible for everyone, or using groups to control
+access. Here is a list, which may still be incomplete (also if there are
+various devices in a form like <filename
+class="devicefile">midi0</filename>, <filename
+class="devicefile">midi1</filename>, ..., then only the 0-version is
+listed here):
+</para>
+
+<itemizedlist>
+<listitem>
+<para>
+<filename class="devicefile">/dev/admmidi0</filename>
+</para>
+</listitem>
+<listitem>
+<para>
+<filename class="devicefile">/dev/adsp0</filename>
+</para>
+</listitem>
+<listitem>
+<para>
+<filename class="devicefile">/dev/amidi0</filename>
+</para>
+</listitem>
+<listitem>
+<para>
+<filename class="devicefile">/dev/amixer0</filename>
+</para>
+</listitem>
+<listitem>
+<para>
+<filename class="devicefile">/dev/audio</filename>
+</para>
+</listitem>
+<listitem>
+<para>
+<filename class="devicefile">/dev/audio0</filename>
+</para>
+</listitem>
+<listitem>
+<para>
+<filename class="devicefile">/dev/cdrom</filename>
+</para>
+</listitem>
+<listitem>
+<para>
+<filename class="devicefile">/dev/dmfm0</filename>
+</para>
+</listitem>
+<listitem>
+<para>
+<filename class="devicefile">/dev/dmmidi0</filename>
+</para>
+</listitem>
+<listitem>
+<para>
+<filename class="devicefile">/dev/dsp</filename>
+</para>
+</listitem>
+<listitem>
+<para>
+<filename class="devicefile">/dev/dsp0</filename>
+</para>
+</listitem>
+<listitem>
+<para>
+<filename class="devicefile">/dev/midi0</filename>
+</para>
+</listitem>
+<listitem>
+<para>
+<filename class="devicefile">/dev/midi0</filename>
+</para>
+</listitem>
+<listitem>
+<para>
+<filename class="devicefile">/dev/midi00</filename>
+</para>
+</listitem>
+<listitem>
+<para>
+<filename class="devicefile">/dev/midi00</filename>
+</para>
+</listitem>
+<listitem>
+<para>
+<filename class="devicefile">/dev/mixer</filename>
+</para>
+</listitem>
+<listitem>
+<para>
+<filename class="devicefile">/dev/mixer0</filename>
+</para>
+</listitem>
+<listitem>
+<para>
+<filename class="devicefile">/dev/mpu401data</filename>
+</para>
+</listitem>
+<listitem>
+<para>
+<filename class="devicefile">/dev/mpu401stat</filename>
+</para>
+</listitem>
+<listitem>
+<para>
+<filename class="devicefile">/dev/music</filename>
+</para>
+</listitem>
+<listitem>
+<para>
+<filename class="devicefile">/dev/rmidi0</filename>
+</para>
+</listitem>
+<listitem>
+<para>
+<filename class="devicefile">/dev/rtc</filename>
+</para>
+</listitem>
+<listitem>
+<para>
+<filename class="devicefile">/dev/sequencer</filename>
+</para>
+</listitem>
+<listitem>
+<para>
+<filename class="devicefile">/dev/smpte0</filename>
+</para>
+</listitem>
+<listitem>
+<para>
+<filename class="devicefile">/dev/sndstat</filename>
+</para>
+</listitem>
+</itemizedlist>
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question>
+<para>What can I do if artsd doesn't start or crashes while running?</para>
+</question>
+
+<answer>
+<para>
+First of all: try using the default settings in &kcontrol; (or if you
+are starting manually, don't give additional options besides maybe
+<userinput><option>-F</option><parameter>10</parameter>
+<option>-S</option><parameter>4096</parameter></userinput> for
+latency). Especially <emphasis>full duplex is likely to break</emphasis>
+with various drivers, so try disabling it.
+</para>
+
+<para>
+A good way to figure out why &artsd; doesn't start (or crashes while
+running) is to start it manually. Open a &konsole; window, and do:
+</para>
+
+<screen width="40"><prompt>%</prompt> <userinput><command>artsd</command> <option>-F</option><parameter>10</parameter> <option>-S</option><parameter>4096</parameter></userinput></screen>
+
+<para>
+You can also add the <option>-l0</option> option, which will print more
+information about what is happening, like this:
+</para>
+<screen width="40"><prompt>%</prompt> <userinput><command>artsd</command> <option>-l0</option> <option>-F</option><parameter>10</parameter> <option>-S</option><parameter>4096</parameter></userinput></screen>
+
+<para>
+Doing so, you will probably get some useful information why it didn't
+start. Or, if it crashes when doing this-and-that, you can do
+this-and-that, and see <quote>how</quote> it crashes. If you want to
+report a bug, producing a backtrace with <command>gdb</command> and/or
+an <command>strace</command> may help finding the problem.
+</para>
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question>
+<para>Can I relocate &artsd; (move compiled files to another
+folder)?</para>
+</question>
+
+<answer>
+<para>
+You can't relocate &arts; perfectly. The problem is that &artswrapper;
+has the location of &artsd; compiled in due to security reasons. You can
+however use the <filename>.mcoprc</filename> file
+(TraderPath/ExtensionPath entries) to at least make a relocated &artsd;
+find it's components. See the <link linkend="the-mcoprc-file">chapter
+about the <filename>.mcoprc</filename> file</link> for details on how to
+do this.
+</para>
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question>
+<para>Can I compile &arts; with gcc-3.0?</para>
+</question>
+
+<answer>
+<para>
+Short answer: no, &arts; will not work if you compile it with gcc-3.0.
+</para>
+
+<para>
+Long answer: In the official release, there are two gcc-3.0 bugs which affect
+&arts;. The first, gcc-3.0 bug c++/2733 is relatively harmless (and has to do
+with problems with the asm statement). It breaks compilation of convert.cc. It
+has been fixed in the gcc-3.0 CVS, and will no longer be a problem with
+gcc-3.0.1 and higher. A workaround has also been added to the CVS version
+of KDE/aRts.
+</para>
+<para>
+The second gcc-3.0 bug, c++/3145 (which is generation of wrong code for some
+cases of multiple virtual inheritance) is critical. Applications like &artsd;
+will simply crash on startup when compiled with gcc-3.0. Even if some progress
+has been made in the gcc-3.0 branch at time of this writing, still &artsd;
+crashes quite often, unpredictably.
+</para>
+</answer>
+</qandaentry>
+<qandaentry>
+<question>
+<para>What applications run under &arts;?</para>
+</question>
+<answer>
+
+<para>
+Obviously, all of the applications included with &kde; are
+&arts;-aware. This includes:
+</para>
+
+<itemizedlist>
+<listitem><para>&noatun;</para></listitem>
+<listitem><para>&arts-builder;</para></listitem>
+<listitem><para>&aktion;</para></listitem>
+<listitem><para>&kmid;</para></listitem>
+<listitem><para>&kmidi;</para></listitem>
+<listitem><para>&kmix;</para></listitem>
+<listitem><para>&kscd;</para></listitem>
+<listitem><para>&kde; games such as &kpoker; and
+&ktuberling;</para></listitem>
+</itemizedlist>
+
+<para>
+Some &kde; applications that are not yet included in the &kde; release
+(&eg; in kdenonbeta) also support &arts;, including:
+</para>
+
+<itemizedlist>
+<listitem><para>&brahms;</para></listitem>
+<listitem><para><application>Kaboodle</application></para></listitem>
+<listitem><para><application>Kdao</application></para></listitem>
+</itemizedlist>
+
+<para>
+The following non-&kde; applications are known to work with &arts;:
+</para>
+
+<itemizedlist>
+<listitem><para><application>xmms</application> (with &arts;
+plug-in)</para></listitem>
+<listitem><para>Real Networks <application>RealPlayer</application> 8.0
+(works with &artsdsp;; native &arts; support is being
+considered)</para></listitem>
+</itemizedlist>
+
+<para>
+The following applications are known <emphasis>not</emphasis> to work
+with &arts;:
+</para>
+
+<itemizedlist>
+<listitem><para>none</para></listitem>
+</itemizedlist>
+
+<para>
+See also the answers to the questions in the section on
+<link linkend="faq-non-arts">non-&arts; applications</link>.
+</para>
+
+<para>
+This section is incomplete -- if you have more information on supported
+and unsupported applications, please send them to the author so they can
+be included here.
+</para>
+</answer>
+</qandaentry>
+
+</qandaset>
+
+<qandaset id="faq-non-arts">
+<title>Non-&arts; Applications</title>
+
+<qandaentry>
+<question>
+<para>
+As soon as &kde; is running, no other application can access my sound device!
+</para>
+</question>
+<answer>
+<para>
+Since the &arts; sound server used by &kde; is running, it is using the
+sound device. If the server is idle for 60 seconds, it will
+auto-suspend and release it automatically.
+</para>
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question>
+<para>
+You said it suspends after 60 seconds, it doesn't for me!
+</para>
+</question>
+<answer>
+<para>
+If you start artsd from the KDE control panel, the default is to suspend
+after 60 seconds. If you start artsd from the command line you need to
+use the -s option to specify the autosuspend time, otherwise it will
+default to disabling the autosuspend feature.
+</para>
+<para>
+Currently it doesn't suspend when using full duplex. Turn full duplex
+off from the &kcontrol; and it will suspend. Disabling full duplex is
+generally a good idea anyway if you only use &arts; for playing audio
+and not recording.
+</para>
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question>
+<para>
+How can I run old, non-&arts; applications?
+</para>
+</question>
+
+<answer>
+<para>
+Run them using the &artsdsp;. For instance, if you normally would run:
+</para>
+
+<screen><prompt>&percnt;</prompt> <userinput><command>mpg123</command> <option>foo.mp3</option></userinput></screen>
+
+<para>instead use:</para>
+
+<screen><prompt>&percnt;</prompt> <userinput><command>artsdsp</command> <option>mpg123 foo.mp3</option></userinput></screen>
+
+<para>
+This will redirect the sound output to &arts;. This method doesn't
+require changes to the applications. It is something of an ugly hack
+however, and does not yet fully support all features of the sound card
+device, so some applications may not work.
+</para>
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question>
+<para>
+I can't run &artsdsp; with any application, it always crashes!
+</para>
+</question>
+<answer>
+<para>
+You need a recent version of the glibc library; &artsdsp; will not work
+reliably on some older &Linux; distributions. For instance, on Debian
+2.1 (which is glibc 2.0 based) it doesn't work, while on Debian 2.2
+(which is glibc 2.1.3 based), it does.
+</para>
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question>
+<para>
+Are there theoretical limitations with some applications that will
+prevent them from ever working with &artsdsp;?
+</para>
+</question>
+<answer>
+<para>
+No. Using &artsdsp; can result in slightly more latency and
+<acronym>CPU</acronym> usage that using the &arts;
+<acronym>API</acronym>s directly. Other than that, any application that
+doesn't work should be considered a bug in &artsdsp;. The technique used
+by &artsdsp; should, if implemented properly, allow
+<emphasis>every</emphasis> application to work with it (including large
+applications like <application>Quake</application> 3).
+</para>
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question>
+<para>
+What can I do if an application doesn't work with &artsdsp;?
+</para>
+</question>
+<answer>
+<para>
+You can wait for &artsd; to suspend or use the command
+<userinput><command>artsshell</command>
+<option>suspend</option></userinput> to ask the server to suspend
+itself. You will only be able to suspend the server if no &arts;
+applications are currently using it, and no &arts; applications will be
+able to run when the server is suspended.
+</para>
+
+<para>
+If the server is busy, a crude but effective way to get rid of it is:
+</para>
+
+
+<screen><prompt>&percnt;</prompt> <userinput><command>killall</command> <option>artsd</option> ; <command>killall</command> <option>artswrapper</option></userinput>
+<lineannotation>Now start your own application.</lineannotation>
+<prompt>&percnt;</prompt> <userinput><command>kcminit</command> <option>arts</option></userinput>
+</screen>
+
+<para>
+Any currently running &arts; applications may crash, however, once you
+kill the server.
+</para>
+</answer>
+</qandaentry>
+<qandaentry>
+<question>
+<para>
+What about applications written for &kde; 1.x?
+</para>
+</question>
+<answer>
+<para>
+If you are running &kde; 1.x applications, which output sound via the
+&kde; 1 audio server, you will need to run
+<application>kaudioserver</application> to make it work. You can start
+<application>kaudioserver</application> in the same way than other
+non-&arts;-applications:
+</para>
+
+<screen>
+<prompt>&percnt;</prompt> <userinput><command>artsdsp</command> <option>kaudioserver</option></userinput>
+</screen>
+
+<para>
+You will need to have installed kaudioserver (from the same source where
+you got your &kde; 1.x applications from) - it belongs to &kde; 1.x, not
+&kde; 2.
+</para>
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question>
+<para>
+What about applications using the enlightened sound daemon,
+<acronym>ESD</acronym>?
+</para>
+</question>
+<answer>
+<para>
+The issue is similar than with
+<application>kaudioserver</application>. Such applications will need a
+running esd server. You can start <command>esd</command> via &artsdsp;,
+and every <acronym>ESD</acronym> aware application should work fine,
+like this:
+</para>
+<screen>
+<prompt>&percnt;</prompt> <userinput><command>artsdsp</command> <option>esd</option></userinput>
+</screen>
+<para>
+Newer versions of aRts (>= 1.2.0) also can also use the enlightened sound
+daemon instead of directly accessing the soundcard. On the command line, you
+can use the -a option, such as
+</para>
+<screen>
+<prompt>&percnt;</prompt> <userinput><command>artsd</command> <option>-a esd</option></userinput>
+</screen>
+<para>
+to get EsounD support, whereas in KDE, you can use kcontrol to configure artsd
+to use esd via Sound -&gt; Sound Server -&gt; Sound I/O.
+</para>
+</answer>
+</qandaentry>
+
+</qandaset>
+
+<qandaset id="faq-latency">
+<title>Latency</title>
+
+<qandaentry>
+<question>
+<para>
+I sometimes hear short pauses when listening to music, is this a bug?
+</para>
+</question>
+<answer>
+<para>
+This is most likely not a bug, but caused by the fact that the &Linux;
+kernel is not very good at real-time scheduling. There are situations
+where &arts; will not be able to keep up with playback. You can,
+however, enable real-time rights (via &kcontrol;), and use a large
+latency setting (like <guilabel>250ms</guilabel> or <guilabel>don't
+care</guilabel>), which should improve the situation.
+</para>
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question>
+<para>
+What's the effect of the response time setting?
+</para>
+</question>
+<answer>
+<para>
+The help text for this setting in the &kcontrol; can be misleading.  A
+lower value means that &arts; will take less time to respond to external
+events (&ie;. the time that it takes between closing a window and
+hearing a sound played by &artsd;). It will also use more
+<acronym>CPU</acronym> resources, and be more likely to cause
+dropouts.</para>
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question>
+<para>
+Is there anything else I can do to prevent pauses?
+</para>
+</question>
+<answer>
+<para>
+For users of <acronym>IDE</acronym> drives, you can use the
+<command>hdparm</command> command to put your <acronym>IDE</acronym>
+drive in <acronym>DMA</acronym> mode. A word of warning: this does not
+work on all hardware, and can result in having to do a hard reset or in
+rare cases, data loss. Read the documentation for the
+<command>hdparm</command> command for more details. I have successfully
+used the following command:
+</para>
+
+<screen>
+<prompt>&percnt;</prompt> <userinput><command>hdparm</command> <option>-c1</option> <option>-d1</option> <option>-k1</option> <option>-K1</option> <parameter>/dev/hda</parameter></userinput>
+</screen>
+
+<para>
+You need to run this after every boot, so you might want to place it in
+a system startup script (how to do this distribution specific, on Debian
+&Linux; it is usually put in <filename>/etc/rc.boot</filename>).
+</para>
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question>
+<para>
+Realtime priority doesn't seem to have any effect for me?
+</para>
+</question>
+<answer>
+<para>
+Verify that artswrapper is really installed suid <systemitem class="username">root</systemitem>, like it is supposed to
+be. A lot of distributions (SuSE7.x for instance) don't do this. You can verify
+this using: ls -l $(which artswrapper). Good:
+<screen>
+<prompt>&percnt;</prompt> <userinput><command>ls</command> <option>-l</option> <parameter>$(which artswrapper)</parameter></userinput>
+-rwsr-xr-x    1 root     root         4556 Sep 24 18:05 /opt/kde2/bin/artswrapper
+</screen>
+Bad:
+<screen>
+<prompt>&percnt;</prompt> <userinput><command>ls</command> <option>-l</option> <parameter>$(which artswrapper)</parameter></userinput>
+-rwxr-xr-x    1 root     root         4556 Sep 24 18:05 /opt/kde2/bin/artswrapper
+</screen>
+If you are not having the s, you can get it using:
+<screen>
+<prompt>&percnt;</prompt> <userinput><command>chown</command> <option>root</option> <parameter>$(which artswrapper)</parameter></userinput>
+<prompt>&percnt;</prompt> <userinput><command>chmod</command> <option>4755</option> <parameter>$(which artswrapper)</parameter></userinput>
+</screen>
+</para>
+
+<para>If you make &artswrapper; SUID <systemitem
+class="username">root</systemitem>, it will likely improve the quality
+of your audio playback by reducing gaps in the music.  However, it
+also increases the risk that a bug in the code or a malicious user can
+crash or otherwise harm your machine.  In addition, on multi-user
+machines, prioritizing high-quality audio may result in deteriorated
+performance for the users who are trying to make
+<quote>productive</quote> use of the machine.</para>
+
+</answer>
+</qandaentry>
+
+
+<qandaentry>
+<question>
+<para>
+Why is &artsd; taking so much <acronym>CPU</acronym> time?
+</para>
+</question>
+<answer>
+<para>
+Check your response time settings. However, the current version is not
+yet really optimized. This will improve, and until then no real
+prediction can be made how fast &artsd; can or can't be.
+</para>
+</answer>
+</qandaentry>
+</qandaset>
+
+<qandaset id="faq-network">
+<title>Network Transparency</title>
+
+<qandaentry>
+<question>
+<para>
+What do I need for network transparency?
+</para>
+</question>
+<answer>
+<para>
+Enable it in the &kcontrol; <guilabel>Sound Server</guilabel> settings
+(<guilabel>enable X11 server for security information</guilabel> and
+<guilabel>network transparency</guilabel>). Then copy your
+<filename>.mcoprc</filename> to all machines you plan to use network
+transparency from. Log in again. Make sure that the hosts that interact
+know each other by name (&ie; they have resolvable names or are in
+<filename>/etc/hosts</filename>).
+</para>
+
+<para>
+This should be all you need to do. However, if it still doesn't work
+here are some additional details. The &arts; sound server process,
+&artsd;, should only run on one host, the one with the sound card where
+the sound should be played. It can be started automatically on login by
+&kde; (if you configure that in &kcontrol;), or manually using something
+like:
+</para>
+
+<screen>
+<prompt>&percnt;</prompt> <userinput><command>artsd</command> <option>-n</option> <option>-F</option> <parameter>5</parameter> <option>-S</option> <parameter>8192</parameter></userinput>
+</screen>
+
+<para>
+The <option>-n</option> parameter is for network transparency, while the
+others configure latency.
+</para>
+
+<para>
+Your <filename>.mcoprc</filename> file should have this entry:
+</para>
+
+<screen>
+<userinput>GlobalComm=Arts::X11GlobalComm</userinput>
+</screen>
+
+<para>
+on all machines involved, in order for network transparency to work,
+This is what is enabled by the <guilabel>X11 server for security
+information</guilabel> control panel setting.
+</para>
+
+<para>
+Finally, in any &kde; version in the 2.0.x series, there is a bug which
+applies if you don't have a domain name set. Clients of &artsd; try to
+find where to connect to via the <systemitem
+class="systemname"><replaceable>hostname</replaceable>.<replaceable>domainname</replaceable></systemitem>
+combination. If your domain name is empty, it will try to connect to
+<systemitem
+class="systemname"><replaceable>hostname</replaceable></systemitem>. (note
+the extra dot). Adding an entry like this to
+<filename>/etc/hosts</filename> (&ie; <userinput>orion.</userinput> if
+your hostname is <systemitem class="systemname">orion</systemitem>)
+works around the problem.
+</para>
+</answer>
+</qandaentry>
+
+
+<qandaentry>
+<question>
+<para>
+How do I debug network transparency if it doesn't work?
+</para>
+</question>
+<answer>
+<para>
+Assuming you have the &kde; source code, go to <filename
+class="directory">kdelibs/arts/examples</filename>, and run
+<userinput><command>make</command> <option>check</option></userinput> to
+compile some programs, including
+<application>referenceinfo</application>. Then run
+</para>
+
+<screen>
+<prompt>&percnt;</prompt> <userinput><command>./referenceinfo</command> <option>global:Arts&lowbar;SimpleSoundServer</option></userinput>
+</screen>
+
+<para>
+The output will indicate the host name and port being used by
+&arts;. For example, <computeroutput>tcp:orion:1698</computeroutput>
+would mean that any client trying to use network transparency should
+know how to reach host <systemitem
+class="systemname">orion</systemitem>.
+</para>
+</answer>
+</qandaentry>
+
+</qandaset>
+
+<qandaset id="faq-hardware-specific">
+<title>Hardware specific questions</title>
+
+<qandaentry>
+<question>
+<para>
+What hardware artsd doesn't work well with?
+</para>
+</question>
+<answer>
+<para>
+It seems that there are a few linux drivers which don't work well with aRts in
+some kernel versions. Please read this list before reporting a bug. If you
+find that some information in this list is incomplete, please don't hesitate
+to let us know.
+
+<informaltable>
+<tgroup cols="4">
+<thead>
+<row>
+<entry>Linux Driver / Soundcard</entry>
+<entry>Fails under</entry>
+<entry>Works under</entry>
+<entry>Remarks</entry>
+</row>
+</thead>
+
+<tbody>
+<row>
+<entry>i810 driver (Intel 810 + AC97 Audio)</entry>
+<entry>2.4.9</entry>
+<entry>2.4.18, 2.2.20, commercial oss driver, alsa-0.5.12a with OSS emulation</entry>
+<entry>driver causes cpu overload (see below)</entry>
+</row>
+
+<row>
+<entry>maestro 3/4 chipset</entry>
+<entry>2.4.9</entry>
+<entry>?</entry>
+<entry>driver sometimes causes cpu overload (see below)</entry>
+</row>
+
+<row>
+<entry>aureal8820, aureal8830 drivers from sourceforge</entry>
+<entry>2.4.17</entry>
+<entry>?</entry>
+<entry>driver triggers assertion / causes cpu overload (see below)</entry>
+</row>
+
+<row>
+<entry>OSS Commercial 3.9.4g with Aureal Vortex</entry>
+<entry>?</entry>
+<entry>?</entry>
+<entry>system lockup</entry>
+</row>
+
+<row>
+<entry>ymfpci</entry>
+<entry>2.4.0, 2.4.12</entry>
+<entry>2.4.17</entry>
+<entry>driver triggers assertion (see below)</entry>
+</row>
+
+
+
+</tbody>
+</tgroup>
+</informaltable>
+</para>
+</answer>
+</qandaentry>
+
+
+
+<qandaentry>
+<question>
+<para>
+Why are there hardware specific problems and how do I see them?
+</para>
+</question>
+<answer>
+<para>
+The usual problem is that the driver doesn't supply aRts with enough or accurate
+enough information on when to write sound data. Most OSS drivers do supply
+correct information, but not all.
+</para>
+<para>
+You might notice that some other applications (like xmms) may not need this
+data, and thus work correctly even with your hardware. However, &arts; needs
+this data, so artsd might fail. This is still a bug in the driver, and not
+in &arts;.
+</para>
+<para>
+There are two kinds of behavior that artsd exposes on being run on an incorrect
+driver. Either, it continously tries to feed new data, but never really
+succeeds, which eventually leads to consuming all CPU power and reporting
+<emphasis>cpu overload</emphasis> and exiting. The other problem is that artsd
+might get supplied with wrong information how much to write. Artsd will then
+<emphasis>stop with an assertion</emphasis> like:
+<screen>
+artsd: audiosubsys.cc:458: void Arts::AudioSubSystem::handleIO(int):
+Assertion `len == can_write' failed.
+Aborted
+</screen>
+</para>
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question>
+<para>
+What is wrong in the driver if I get the cpu overload problem?
+</para>
+</question>
+<answer>
+<para>
+Usually, artsd uses select() to find out when to write new data. Then, it
+uses an ioctl(...GETOSPACE...) to find out how much data to write. Finally,
+it writes this data.
+</para>
+<para>
+A problem occurs if artsd is woken up either always or if there are minimal
+amounts of data to write. The OSS documentation specifies that select() only
+wakes up a process if there is at least one fragment to write. However, if
+artsd is woken up if there isn't data to write, or very little, for instance
+one sample, then it will keep writing little pieces of audio data, which can
+be very costly, and eventually overload the cpu.
+</para>
+<para>
+To fix this, the driver should wake up artsd only if there is a full fragment
+to write.
+</para>
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question>
+<para>
+What is wrong in the driver if I get the assertion?
+</para>
+</question>
+<answer>
+<para>
+Usually, artsd uses select() to find out when to write new data. Then, it
+uses an ioctl(...GETOSPACE...) to find out how much data to write. Finally,
+it writes this data.
+</para>
+<para>
+If artsd can't write as much data as indicated by the ioctl, it will fail in
+the assertion. To fix this, the driver should supply the correct amount of
+free space.
+</para>
+</answer>
+</qandaentry>
+</qandaset>
+
+<qandaset id="faq-other">
+<title>Other Issues</title>
+
+<qandaentry>
+<question>
+<para>
+I can't use &arts-builder;. It crashes when executing a module!
+</para>
+</question>
+<answer>
+<para>
+The most likely cause is that you are using old structures or modules
+which aren't supported with the &kde; 2 version. Unfortunately the
+documentation which is on the web refers to &arts;-0.3.4.1 which is
+quite outdated. The most often reported crash is: that performing an
+execute structure in &arts-builder; results in the error message
+<errorname>[artsd] Synth_PLAY: audio subsystem is already
+used.</errorname>
+</para>
+
+<para>
+You should use a Synth_AMAN_PLAY instead of a Synth_PLAY module and the
+problem will go away. Also see the &arts-builder; help file (hit
+<keycap>F1</keycap> in &arts-builder;).
+</para>
+
+<para>
+Recent versions of &arts-builder; (&kde; 2.1 beta 1 and later) come with
+a set of examples which you can use.
+</para>
+</answer>
+</qandaentry>
+
+</qandaset>
+
+</chapter>