path: root/doc/artsbuilder/tools.docbook

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