1
<!-- <?xml version="1.0" ?>
2
<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.1-Based Variant V1.0//EN" "dtd/kdex.dtd">
4
To validate or process this file as a standalone document, uncomment
5
this prolog. Be sure to comment it out again when you are done -->
7
<chapter id="arts-tools">
8
<title>&arts; Tools</title>
11
Included with &arts; is a number of utilities for controlling and
12
configuring its behavior. You need to have some familiarity with most of
13
these tools in order to use &arts; effectively. This section describes
14
each of the utilities and their command options.
17
<sect1 id="kde-control-center">
18
<title>&kcontrol;</title>
21
When running &arts; under &kde;, the &kcontrolcenter; provides a group
22
of control panel settings under the <guilabel>Sound</guilabel>
23
category. Some of these settings are used by &arts;. You can also
24
associate sounds with various window manager and &kde; events using the
25
<menuchoice><guilabel>Look & Feel</guilabel><guilabel>System
26
Notifications</guilabel></menuchoice> panel. See the &kcontrol; manual
27
for information on using the panel settings.
33
<title>&artsd;</title>
36
Access to the sound hardware resources is controlled by &artsd;, the
37
&arts; daemon. This allows different applications to simultaneously send
38
requests to the server, where they can be mixed together and
39
played. Without a centralized sound server a single application using a
40
sound device would prevent other applications from using it.
44
To use &arts; there should be one and only one copy of &artsd;
45
running. It is typically run when &kde; starts up if it is enabled in
46
the &kcontrol; <guilabel>Sound Server</guilabel> panel.
49
<para>The program accepts the following arguments:</para>
54
<command>artsd</command>
59
<option>-W <replaceable>n</replaceable></option>
63
<option>-a <replaceable>audiomethod</replaceable></option>
64
<option>-r <replaceable>sampling rate</replaceable></option>
65
<option>-b <replaceable>bits</replaceable></option>
67
<option>-D <replaceable>devicename</replaceable></option>
68
<option>-F <replaceable>fragments</replaceable></option>
69
<option>-S <replaceable>size</replaceable></option>
70
<option>-s <replaceable>seconds</replaceable></option>
71
<option>-m <replaceable>appName</replaceable></option>
77
<option>-l <replaceable>level</replaceable></option>
81
<variablelist><varlistentry>
82
<term><option>-r <replaceable>sampling rate</replaceable></option></term>
84
<para>Set sampling rate to use.</para>
89
<term><option>-h</option></term>
91
<para>Display command usage.</para>
96
<term><option>-n</option></term>
98
<para>Enable network transparency.</para>
103
<term><option>-p <replaceable>port</replaceable></option>
106
<para>Set <acronym>TCP</acronym> port to use (implies
107
<option>-n</option>).</para>
112
<term><option>-u</option></term>
114
<para>Public, no authentication (dangerous).</para>
119
<term><option>-d</option></term>
121
<para>Enable full duplex operation.</para>
125
<term><option>-D <replaceable>device name</replaceable></option></term>
127
<para>Specify audio device (usually <filename>/dev/dsp</filename>).</para>
132
<term><option>-F <replaceable>fragments</replaceable></option></term>
134
<para>Set number of fragments.</para>
139
<term><option>-S <replaceable>size</replaceable></option></term>
141
<para>Set fragment size, in bytes.</para>
146
<term><option>-s <replaceable>seconds</replaceable></option></term>
148
<para>Set server auto-suspend time, in seconds. A value of zero
149
disables auto-suspend.</para>
154
<term><option>-m <replaceable>appName</replaceable></option></term>
156
<para>Specify the name of an application to be used to display error,
157
warning, and informational messages. If you are running KDE you can
158
use the <application>artsmessage</application> utility for this.</para>
163
<term><option>-N</option></term>
166
Increase the size of network buffers to a value suitable for running over
167
a 10 mbps LAN. This is equivalent to using the -w 5 option (see below).
172
<term><option>-w <replaceable>n</replaceable></option></term>
175
When running <application>artsd</application> over a network connection
176
to another host you typically want to use a larger buffer size to
177
avoid dropouts. ARts provides applications with a suggested minimum
178
buffer size. Without this option the default size is based on the
179
fragement size * fragment count. Using this option you can increase
180
the size from the default by a factor of <replaceable>n</replaceable>.
186
<term><option>-l <replaceable>level</replaceable></option></term>
188
<para>Set information level - 3 (quiet), 2 (warnings), 1 (info), 0
194
<term><option>-v</option></term>
196
<para>Display version level.</para>
203
In most cases simply running &artsd; will suffice.
207
<sect1 id="artswrapper">
208
<title>&artswrapper;</title>
211
To provide good real-time response, &artsd; is usually run as a
212
real-time process (on platforms where real-time priorities are
213
supported). This requires <systemitem class="username">root</systemitem>
214
permissions, so to minimize the security implications, &artsd; can be
215
started using the small wrapper program &artswrapper; which simply sets
216
real-time priority (running as <systemitem
217
class="username">root</systemitem>) and then executes &artsd; as a
218
non-<systemitem class="username">root</systemitem> user.
223
<sect1 id="artsshell">
224
<title>&artsshell;</title>
227
The &artsshell; command is intended as a utility to perform
228
miscellaneous functions related to the sound server. It is expected that
229
the utility will be extended with new commands in the future (see the
230
comments in the source code for some ideas).
234
The command accepts the following format:
237
<!-- LW: FIX THIS -->
240
<command>artsshell</command>
242
<arg>suspend</arg><arg>status</arg>
244
<arg>autosuspend <replaceable>secs</replaceable></arg>
245
<arg>networkbuffers <replaceable>n</replaceable></arg>
246
<arg>volume [<replaceable>volume</replaceable>]</arg>
247
<arg>stereoeffect <replaceable>options</replaceable></arg>
255
<para>artsshell [options] <replaceable>command</replaceable> [<replaceable>command-options</replaceable>] </para>
258
The following options are supported:
264
<term><option>-q</option></term>
266
<para>Suppress all output.</para>
271
<term><option>-h</option></term>
273
<para>Display command usage.</para>
279
<para>The following commands are supported:</para>
284
<term><option>suspend</option></term>
287
Suspend the sound server.
293
<term><option>status</option></term>
295
<para>Display sound server status information.</para>
300
<term><option>terminate</option></term>
303
Terminate the sound server. This may confuse and/or crash any
304
applications that are currently using it.
310
<term><option>autosuspend</option> <parameter>seconds</parameter></term>
313
Set the autosuspend time to the specified number of seconds. The sound
314
server will suspend itself if idle for that period of time. A value of
315
zero disables auto-suspend.
321
<term><option>networkbuffers</option> <parameter>n</parameter></term>
324
Set the size of the nework buffers to be a factor of
325
<parameter>n</parameter> times the default size.
331
<term><option>volume</option> [<replaceable>volume</replaceable>]</term>
334
Sets volume scaling for sound server audio output. The
335
<replaceable>volume</replaceable> argument is a floating point
336
value. With no argument the current volume is displayed.
342
<term><option>stereoeffect list</option></term>
344
<para>List all of the available stereo effect modules.</para>
349
<term><option>stereoeffect insert [top|bottom]</option> <replaceable>name</replaceable></term>
351
<para>Insert a stereo effect into the stereo effect stack. Returns
352
an identifier that can be used for later removing it. It can be
353
installed at the top or the bottom (the default).</para>
358
<term><option>stereoeffect remove</option> <replaceable>id</replaceable></term>
360
<para>Removes the stereo effect with identifier
361
<replaceable>id</replaceable> from the effects stack.</para>
369
<sect1 id="artsplay">
370
<title><application>artsplay</application></title>
372
<para>The <application>artsplay</application> command is a simple utility to
373
play a sound file. It accepts a single argument corresponding to the name of a
374
sound file which is sent to the sound server to be played. The sound
375
file can be any common sound file type such as <literal
376
role="extension">wav</literal> or <literal
377
role="extension">au</literal>. This utility is good for testing that the
378
sound server is working. By running two commands in parallel or in rapid
379
succession you can demonstrate how the sound servers mixes more than one
385
<title><application>artsdsp</application></title>
388
The sound server only supports applications that are &arts;-aware. Many
389
legacy applications want to access the sound device directly. The
390
&artsdsp; command provides an interim solution that
391
allows most of these applications to run unchanged.
395
When an application is run under &artsdsp; all accesses to the <filename
396
class="devicefile">/dev/dsp</filename> audio device are intercepted and
397
mapped into &arts; <acronym>API</acronym> calls. While the device
398
emulation is not perfect, most applications work this way, albeit with
399
some degradation in performance and latency.
402
<para>The &artsdsp; command follows the format:
405
<!-- LW: FIX THIS -->
407
artsdsp [<replaceable>options</replaceable>] <replaceable>application arguments</replaceable>
411
The following options are recognized:
417
<term><option>-h</option>, <option>--help</option></term>
419
<para>Show brief help.</para>
423
<term><option>-n</option> <option>--name</option> = <replaceable>name</replaceable></term>
425
<para>Use <replaceable>name</replaceable> to identify player to <command>artsd</command>.</para>
431
<term><option>-m</option> <option>--mmap</option></term>
433
<para>Emulate memory mapping (⪚ for <application>Quake</application>).</para>
438
<term><option>-v</option> <option>--verbose</option></term>
440
<para>Show parameters.</para>
447
A typical invocation is:
451
<userinput><command>artsdsp</command> <option>-v</option> <option>-m</option> <parameter>realplay <replaceable>song.mp3</replaceable></parameter></userinput>
455
Some applications work better with the <option>--mmap</option>
456
option. Not all features of the sound device are fully emulated, but
457
most applications should work. If you find one that does not, submit a
458
detailed bug report and the developers may be able to fix it. Again,
459
remember this is an interim solution and something of an ugly hack; the
460
best solution is to add native &arts; support to the applications. If
461
your favorite sound application does not have &arts; support, ask the
462
developer to provide it.
468
<title><application>artscat</application></title>
471
This is a simple utility to send raw audio data to the sound server.
472
You need to specify the data format (sampling rate, sample size, and
473
number of channels). This is probably not a utility that you will use
474
often, but it can be handy for testing purposes. The command syntax is:
477
<!-- LW: FIX THIS -->
480
artscat [ <replaceable>options</replaceable> ] [ <replaceable>filename</replaceable> ]
484
If no file name is specified, it reads standard input. The following
485
options are supported:
490
<term><option>-r</option> <parameter>sampling
491
rate</parameter></term>
494
Set the sampling rate to use.
500
<term><option>-b</option> <parameter>bits</parameter></term>
503
Set sample size to use (8 or 16).
509
<term><option>-c</option> <parameter>channels</parameter></term>
512
Set number of channels (1 or 2).
518
<term><option>-h</option></term>
521
Display command usage and exit.
529
<sect1 id="artscontrol">
530
<title>&artscontrol;</title>
533
This is a graphical utility for performing a number of tasks related to
534
the sound server. The default window displays two volume level
535
indicators and a slider to control overall output volume. From the
536
<guimenu>View</guimenu> menu you can select other functions:
542
<term><guimenuitem>FFT Scope</guimenuitem></term>
545
Opens a window which shows a real-time spectrum analyzer style display.
551
<term><guimenuitem>Audio Manager</guimenuitem></term>
554
Displays active sound sources and allows you to connect them to any of
555
the available busses.
561
<term><guimenuitem>aRts Status</guimenuitem></term>
564
Shows if the sound server is running and if scheduling is
565
real-time. Indicates when server will autosuspend and allows you to
566
suspend it immediately.
572
<term><guimenuitem>Midi Manager</guimenuitem></term>
575
Shows active &MIDI; inputs and outputs and allows you to make connections
576
[TODO: Does this work yet? Need more detail].
582
<term><guimenuitem>FreeVerb</guimenuitem></term>
585
Connects a FreeVerb reverb effect to the stack of &arts; output effects
586
and allows you to control the effect parameters graphically.
592
<term><guimenuitem>Leds-like volume display</guimenuitem></term>
595
Changes the volume indicators in the main window to use a colored
596
<acronym>LED</acronym> display format instead of progress bars.
605
<sect1 id="artsc-config">
606
<title><application>artsc-config</application></title>
609
This is a utility to assist developers using the &arts; C
610
<acronym>API</acronym>. It outputs the appropriate compiler and linker
611
options needed when compiling and linking code with &arts;. It is
612
intended to be used within make files to assist in portability. The
613
command accepts three options:
618
<term><option>--cflags</option></term>
621
Displays the compiler flags needed when compiling with the &arts; C
622
<acronym>API</acronym>.
628
<term><option>--libs</option></term>
631
Displays the linker flags needed when linking with the &arts; C
632
<acronym>API</acronym>.
637
<term><acronym>--version</acronym></term>
640
Displays the version of the <command>artsc-config</command> command.
646
<para>Typical output from the command is shown below:</para>
649
<prompt>%</prompt> <userinput><command>artsc-config</command> <option>--cflags</option></userinput>
650
<computeroutput>-I/usr/local/kde2/include/artsc</computeroutput>
651
<prompt>%</prompt> <userinput><command>artsc-config</command> <option>--libs</option></userinput>
652
<computeroutput>-L/usr/local/kde2/lib -ldl -lartsc -DPIC -fPIC -lpthread</computeroutput>
653
<prompt>%</prompt> <userinput><command>artsc-config</command> <option>--version</option></userinput>
654
<computeroutput>0.9.5</computeroutput>
658
You could use this utility in a make file using a rule such as:
663
gcc `artsc-config --cflags` -o artsc artsc.c `artsc-config --libs`
669
<title>&mcopidl;</title>
672
The &mcopidl; command is the &IDL; file compiler for &MCOP;, the
673
Multimedia Communication Protocol used by &arts;. Interfaces in &arts;
674
are defined in &IDL;, a language independent Interface Definition
675
Language. The &mcopidl; utility accepts an &IDL; file as input and
676
generates C++ header and source files for a class implementing the
677
interface. The command accepts the following syntax:
680
<!-- LW: FIX THIS -->
682
<para>mcopidl [ <replaceable>options</replaceable> ] <replaceable>filename</replaceable>
685
<para>The valid options are:</para>
688
<term><option>-I</option> <parameter>directory</parameter></term>
691
Search in <parameter>directory</parameter> for includes.
697
<term><option>-e</option> <parameter>name</parameter></term>
700
Exclude a struct, interface, or enum type <parameter>name</parameter>
701
from code generation.
707
<term><option>-t</option></term>
710
Also create <literal role="extension">.mcoptype</literal>/<literal
711
role="extension">.mcopclass</literal> files containing type information
719
More information about &MCOP; and &IDL; is covered in the section <link
720
linkend="interfaces">Interfaces and &IDL;</link>.
added
removed
doc/artsbuilder/tools.docbook
