1 files changed, 735 insertions, 0 deletions
diff --git a/doc/artsbuilder/tools.docbook b/doc/artsbuilder/tools.docbook
new file mode 100644
index 00000000..417951df
--- /dev/null
+++ b/doc/artsbuilder/tools.docbook
@@ -0,0 +1,735 @@
+<!-- 
+<?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="arts-tools">
+<title>&arts; Tools</title>
+
+<para>
+Included with &arts; is a number of utilities for controlling and
+configuring its behavior. You need to have some familiarity with most of
+these tools in order to use &arts; effectively. This section describes
+each of the utilities and their command options.
+</para>
+
+<sect1 id="kde-control-center">
+<title>&kcontrol;</title>
+
+<para>
+When running &arts; under &kde;, the &kcontrolcenter; provides a group
+of control panel settings under the <guilabel>Sound</guilabel>
+category. Some of these settings are used by &arts;. You can also
+associate sounds with various window manager and &kde; events using the
+<menuchoice><guilabel>Look &amp; Feel</guilabel><guilabel>System
+Notifications</guilabel></menuchoice> panel. See the &kcontrol; manual
+for information on using the panel settings.
+</para>
+
+</sect1>
+
+<sect1 id="artsd">
+<title>&artsd;</title>
+
+<para>
+Access to the sound hardware resources is controlled by &artsd;, the
+&arts; daemon. This allows different applications to simultaneously send
+requests to the server, where they can be mixed together and
+played. Without a centralized sound server a single application using a
+sound device would prevent other applications from using it.
+</para>
+
+<para>
+To use &arts; there should be one and only one copy of &artsd;
+running. It is typically run when &kde; starts up if it is enabled in
+the &kcontrol; <guilabel>Sound Server</guilabel> panel.
+</para>
+
+<para>The program accepts the following arguments:</para>
+
+<!-- LW: FIX THIS -->
+
+<cmdsynopsis>
+<command>artsd</command>
+<group choice="opt">
+<option>-n</option>
+<option>-p</option>
+<option>-N</option>
+<option>-W <replaceable>n</replaceable></option>
+
+</group>
+<group choice="opt">
+<option>-a <replaceable>audiomethod</replaceable></option>
+<option>-r <replaceable>sampling rate</replaceable></option>
+<option>-b <replaceable>bits</replaceable></option>
+<option>-d</option>
+<option>-D <replaceable>devicename</replaceable></option>
+<option>-F <replaceable>fragments</replaceable></option>
+<option>-S <replaceable>size</replaceable></option>
+<option>-s <replaceable>seconds</replaceable></option>
+<option>-m <replaceable>appName</replaceable></option>
+</group>
+<group choice="opt">
+<option>-h</option>
+<option>-A</option>
+<option>-v</option>
+<option>-l <replaceable>level</replaceable></option>
+</group>
+</cmdsynopsis>
+
+<variablelist><varlistentry>
+<term><option>-r <replaceable>sampling rate</replaceable></option></term>
+<listitem>
+<para>Set sampling rate to use.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-h</option></term>
+<listitem>
+<para>Display command usage.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-n</option></term>
+<listitem>
+<para>Enable network transparency.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-p <replaceable>port</replaceable></option>
+</term>
+<listitem>
+<para>Set <acronym>TCP</acronym> port to use (implies
+<option>-n</option>).</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-u</option></term>
+<listitem>
+<para>Public, no authentication (dangerous).</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-d</option></term>
+<listitem>
+<para>Enable full duplex operation.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><option>-D <replaceable>device name</replaceable></option></term>
+<listitem>
+<para>Specify audio device (usually <filename>/dev/dsp</filename>).</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-F <replaceable>fragments</replaceable></option></term>
+<listitem>
+<para>Set number of fragments.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-S <replaceable>size</replaceable></option></term>
+<listitem>
+<para>Set fragment size, in bytes.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-s <replaceable>seconds</replaceable></option></term>
+<listitem>
+<para>Set server auto-suspend time, in seconds. A value of zero
+disables auto-suspend.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-m <replaceable>appName</replaceable></option></term>
+<listitem>
+<para>Specify the name of an application to be used to display error,
+warning, and informational messages. If you are running KDE you can
+use the <application>artsmessage</application> utility for this.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-N</option></term>
+<listitem>
+<para>
+Increase the size of network buffers to a value suitable for running over
+a 10 mbps LAN. This is equivalent to using the -w 5 option (see below).
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><option>-w <replaceable>n</replaceable></option></term>
+<listitem>
+<para>
+When running <application>artsd</application> over a network connection
+to another host you typically want to use a larger buffer size to
+avoid dropouts. ARts provides applications with a suggested minimum
+buffer size. Without this option the default size is based on the
+fragment size * fragment count. Using this option you can increase
+the size from the default by a factor of <replaceable>n</replaceable>.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-l <replaceable>level</replaceable></option></term>
+<listitem>
+<para>Set information level - 3 (quiet), 2 (warnings), 1 (info), 0
+(debug).</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-v</option></term>
+<listitem>
+<para>Display version level.</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+
+<para>
+In most cases simply running &artsd; will suffice.
+</para>
+</sect1>
+
+<sect1 id="artswrapper">
+<title>&artswrapper;</title>
+
+<para>
+To provide good real-time response, &artsd; is usually run as a
+real-time process (on platforms where real-time priorities are
+supported). This requires <systemitem class="username">root</systemitem>
+permissions, so to minimize the security implications, &artsd; can be
+started using the small wrapper program &artswrapper; which simply sets
+real-time priority (running as <systemitem
+class="username">root</systemitem>) and then executes &artsd; as a
+non-<systemitem class="username">root</systemitem> user.
+</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>
+
+</sect1>
+
+<sect1 id="artsshell">
+<title>&artsshell;</title>
+
+<para>
+The &artsshell; command is intended as a utility to perform
+miscellaneous functions related to the sound server. It is expected that
+the utility will be extended with new commands in the future (see the
+comments in the source code for some ideas).
+</para>
+
+<para>
+The command accepts the following format:
+</para>
+
+<!-- LW: FIX THIS -->
+
+<cmdsynopsis>
+<command>artsshell</command>
+<group>
+<arg>suspend</arg><arg>status</arg>
+<arg>terminate</arg>
+<arg>autosuspend <replaceable>secs</replaceable></arg>
+<arg>networkbuffers <replaceable>n</replaceable></arg>
+<arg>volume [<replaceable>volume</replaceable>]</arg>
+<arg>stereoeffect <replaceable>options</replaceable></arg>
+</group>
+<group>
+<option>-h</option>
+<option>-q</option>
+</group>
+</cmdsynopsis>
+
+<para>artsshell [options] <replaceable>command</replaceable> [<replaceable>command-options</replaceable>] </para>
+
+<para>
+The following options are supported:
+</para>
+
+<variablelist>
+
+<varlistentry>
+<term><option>-q</option></term>
+<listitem>
+<para>Suppress all output.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-h</option></term>
+<listitem>
+<para>Display command usage.</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+
+<para>The following commands are supported:</para>
+
+<variablelist>
+
+<varlistentry>
+<term><option>suspend</option></term>
+<listitem>
+<para>
+Suspend the sound server.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>status</option></term>
+<listitem>
+<para>Display sound server status information.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>terminate</option></term>
+<listitem>
+<para>
+Terminate the sound server. This may confuse and/or crash any
+applications that are currently using it.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>autosuspend</option> <parameter>seconds</parameter></term>
+<listitem>
+<para>
+Set the autosuspend time to the specified number of seconds. The sound
+server will suspend itself if idle for that period of time. A value of
+zero disables auto-suspend.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>networkbuffers</option> <parameter>n</parameter></term>
+<listitem>
+<para>
+Set the size of the network buffers to be a factor of
+<parameter>n</parameter> times the default size.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>volume</option> [<replaceable>volume</replaceable>]</term>
+<listitem>
+<para>
+Sets volume scaling for sound server audio output. The
+<replaceable>volume</replaceable> argument is a floating point
+value. With no argument the current volume is displayed.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>stereoeffect list</option></term>
+<listitem>
+<para>List all of the available stereo effect modules.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>stereoeffect insert [top|bottom]</option> <replaceable>name</replaceable></term>
+<listitem>
+<para>Insert a stereo effect into the stereo effect stack. Returns
+an identifier that can be used for later removing it. It can be
+installed at the top or the bottom (the default).</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>stereoeffect remove</option> <replaceable>id</replaceable></term>
+<listitem>
+<para>Removes the stereo effect with identifier
+<replaceable>id</replaceable> from the effects stack.</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+
+</sect1>
+
+<sect1 id="artsplay">
+<title><application>artsplay</application></title>
+
+<para>The <application>artsplay</application> command is a simple utility to
+play a sound file. It accepts a single argument corresponding to the name of a
+sound file which is sent to the sound server to be played. The sound
+file can be any common sound file type such as <literal
+role="extension">wav</literal> or <literal
+role="extension">au</literal>. This utility is good for testing that the
+sound server is working. By running two commands in parallel or in rapid
+succession you can demonstrate how the sound servers mixes more than one
+sound source.</para>
+
+</sect1>
+
+<sect1 id="artsdsp">
+<title><application>artsdsp</application></title>
+
+<para>
+The sound server only supports applications that are &arts;-aware.  Many
+legacy applications want to access the sound device directly.  The
+&artsdsp; command provides an interim solution that
+allows most of these applications to run unchanged.
+</para>
+
+<para>
+When an application is run under &artsdsp; all accesses to the <filename
+class="devicefile">/dev/dsp</filename> audio device are intercepted and
+mapped into &arts; <acronym>API</acronym> calls. While the device
+emulation is not perfect, most applications work this way, albeit with
+some degradation in performance and latency.
+</para>
+
+<para>The &artsdsp; command follows the format:
+</para>
+
+<!-- LW: FIX THIS -->
+<para>
+artsdsp [<replaceable>options</replaceable>] <replaceable>application arguments</replaceable>
+</para>
+
+<para>
+The following options are recognized:
+</para>
+
+<variablelist>
+
+<varlistentry>
+<term><option>-h</option>,  <option>--help</option></term>
+<listitem>
+<para>Show brief help.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><option>-n</option> <option>--name</option> = <replaceable>name</replaceable></term>
+<listitem>
+<para>Use <replaceable>name</replaceable> to identify player to <command>artsd</command>.</para>
+
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-m</option> <option>--mmap</option></term>
+<listitem>
+<para>Emulate memory mapping (&eg; for <application>Quake</application>).</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-v</option> <option>--verbose</option></term>
+<listitem>
+<para>Show parameters.</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+
+<para>
+A typical invocation is:
+</para>
+
+<para>
+<userinput><command>artsdsp</command> <option>-v</option> <option>-m</option> <parameter>realplay <replaceable>song.mp3</replaceable></parameter></userinput>
+</para>
+
+<para>
+Some applications work better with the <option>--mmap</option>
+option. Not all features of the sound device are fully emulated, but
+most applications should work. If you find one that does not, submit a
+detailed bug report and the developers may be able to fix it. Again,
+remember this is an interim solution and something of an ugly hack; the
+best solution is to add native &arts; support to the applications.  If
+your favorite sound application does not have &arts; support, ask the
+developer to provide it.
+</para>
+
+</sect1>
+
+<sect1 id="artscat">
+<title><application>artscat</application></title>
+
+<para>
+This is a simple utility to send raw audio data to the sound server.
+You need to specify the data format (sampling rate, sample size, and
+number of channels). This is probably not a utility that you will use
+often, but it can be handy for testing purposes. The command syntax is:
+</para>
+
+<!-- LW: FIX THIS -->
+ 
+<para>
+artscat [ <replaceable>options</replaceable> ] [ <replaceable>filename</replaceable> ]
+</para>
+
+<para>
+If no file name is specified, it reads standard input. The following
+options are supported:
+</para>
+
+<variablelist>
+<varlistentry>
+<term><option>-r</option> <parameter>sampling
+rate</parameter></term>
+<listitem>
+<para>
+Set the sampling rate to use.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-b</option> <parameter>bits</parameter></term>
+<listitem>
+<para>
+Set sample size to use (8 or 16).
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-c</option> <parameter>channels</parameter></term>
+<listitem>
+<para>
+Set number of channels (1 or 2).
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-h</option></term>
+<listitem>
+<para>
+Display command usage and exit.
+</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+</sect1>
+
+<sect1 id="artscontrol">
+<title>&artscontrol;</title>
+
+<para>
+This is a graphical utility for performing a number of tasks related to
+the sound server. The default window displays two volume level
+indicators and a slider to control overall output volume. From the
+<guimenu>View</guimenu> menu you can select other functions:
+</para>
+
+<variablelist>
+
+<varlistentry>
+<term><guimenuitem>FFT Scope</guimenuitem></term>
+<listitem>
+<para>
+Opens a window which shows a real-time spectrum analyzer style display.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guimenuitem>Audio Manager</guimenuitem></term>
+<listitem>
+<para>
+Displays active sound sources and allows you to connect them to any of
+the available busses.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guimenuitem>aRts Status</guimenuitem></term>
+<listitem>
+<para>
+Shows if the sound server is running and if scheduling is
+real-time. Indicates when server will autosuspend and allows you to
+suspend it immediately.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guimenuitem>Midi Manager</guimenuitem></term>
+<listitem>
+<para>
+Shows active &MIDI; inputs and outputs and allows you to make connections
+[TODO: Does this work yet? Need more detail]. 
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guimenuitem>FreeVerb</guimenuitem></term>
+<listitem>
+<para>
+Connects a FreeVerb reverb effect to the stack of &arts; output effects
+and allows you to control the effect parameters graphically.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guimenuitem>Leds-like volume display</guimenuitem></term>
+<listitem>
+<para>
+Changes the volume indicators in the main window to use a colored
+<acronym>LED</acronym> display format instead of progress bars.
+</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+
+</sect1>
+
+<sect1 id="artsc-config">
+<title><application>artsc-config</application></title>
+
+<para>
+This is a utility to assist developers using the &arts; C
+<acronym>API</acronym>. It outputs the appropriate compiler and linker
+options needed when compiling and linking code with &arts;. It is
+intended to be used within make files to assist in portability. The
+command accepts three options:
+</para>
+
+<variablelist>
+<varlistentry>
+<term><option>--cflags</option></term>
+<listitem>
+<para>
+Displays the compiler flags needed when compiling with the &arts; C
+<acronym>API</acronym>.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--libs</option></term>
+<listitem>
+<para>
+Displays the linker flags needed when linking with the &arts; C
+<acronym>API</acronym>.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><acronym>--version</acronym></term>
+<listitem>
+<para>
+Displays the version of the <command>artsc-config</command> command.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+<para>Typical output from the command is shown below:</para>
+
+<screen width="40">
+<prompt>%</prompt> <userinput><command>artsc-config</command> <option>--cflags</option></userinput>
+<computeroutput>-I/usr/local/kde2/include/artsc</computeroutput>
+<prompt>%</prompt> <userinput><command>artsc-config</command> <option>--libs</option></userinput>
+<computeroutput>-L/usr/local/kde2/lib -ldl -lartsc -DPIC -fPIC -lpthread</computeroutput>
+<prompt>%</prompt> <userinput><command>artsc-config</command> <option>--version</option></userinput>
+<computeroutput>0.9.5</computeroutput>
+</screen>
+
+<para>
+You could use this utility in a make file using a rule such as:
+</para>
+
+<programlisting>
+artsc: artsc.c
+        gcc `artsc-config --cflags` -o artsc artsc.c `artsc-config --libs`
+</programlisting>
+
+</sect1>
+
+<sect1 id="mcopidl">
+<title>&mcopidl;</title>
+
+<para>
+The &mcopidl; command is the &IDL; file compiler for &MCOP;, the
+Multimedia Communication Protocol used by &arts;. Interfaces in &arts;
+are defined in &IDL;, a language independent Interface Definition
+Language. The &mcopidl; utility accepts an &IDL; file as input and
+generates C++ header and source files for a class implementing the
+interface. The command accepts the following syntax:
+</para>
+
+<!-- LW: FIX THIS -->
+
+<para>mcopidl [ <replaceable>options</replaceable> ] <replaceable>filename</replaceable>
+</para>
+
+<para>The valid options are:</para>
+<variablelist>
+<varlistentry>
+<term><option>-I</option> <parameter>directory</parameter></term>
+<listitem>
+<para>
+Search in <parameter>directory</parameter> for includes.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-e</option> <parameter>name</parameter></term>
+<listitem>
+<para>
+Exclude a struct, interface, or enum type <parameter>name</parameter>
+from code generation.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-t</option></term>
+<listitem>
+<para>
+Also create <literal role="extension">.mcoptype</literal>/<literal 
+role="extension">.mcopclass</literal> files containing type information
+for the &IDL; file.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+<para>
+More information about &MCOP; and &IDL; is covered in the section <link
+linkend="interfaces">Interfaces and &IDL;</link>.
+</para>
+
+</sect1>
+
+</chapter>