# &arts; Tools

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.

## &kcontrol;

When running &arts; under &kde;, the &kcontrolcenter; provides a group of control panel settings under the Sound category. Some of these settings are used by &arts;. You can also associate sounds with various window manager and &kde; events using the Look & Feel System Notifications panel. See the &kcontrol; manual for information on using the panel settings.

## &artsd;

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.

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; Sound Server panel.

The program accepts the following arguments:

    artsd

    -n
    -p
    -N
    -W n

    -a audiomethod
    -r sampling rate
    -b bits
    -d
    -D devicename
    -F fragments
    -S size
    -s seconds
    -m appName

    -h
    -A
    -v
    -l level

`-r sampling rate`

  Set sampling rate to use.

`-h`

  Display command usage.

`-n`

  Enable network transparency.

`-p port`

  Set TCP port to use (implies `-n`).

`-u`

  Public, no authentication (dangerous).

`-d`

  Enable full duplex operation.

`-D device name`

  Specify audio device (usually `/dev/dsp`).

`-F fragments`

  Set number of fragments.

`-S size`

  Set fragment size, in bytes.

`-s seconds`

  Set server auto-suspend time, in seconds. A value of zero disables auto-suspend.

`-m appName`

  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 artsmessage utility for this.

`-N`

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

`-w n`

  When running artsd 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 n.

`-l level`

  Set information level - 3 (quiet), 2 (warnings), 1 (info), 0 (debug).

`-v`

  Display version level.

In most cases simply running &artsd; will suffice.

## &artswrapper;

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 root 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 root) and then executes &artsd; as a non-root user.

If you make artswrapper SUID root, 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 productive use of the machine.

## &artsshell;

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

The command accepts the following format:

    artsshell

    suspendstatus
    terminate
    autosuspend secs
    networkbuffers n
    volume [volume]
    stereoeffect options

    -h
    -q

artsshell [options] command [command-options]

The following options are supported:

`-q`

  Suppress all output.

`-h`

  Display command usage.

The following commands are supported:

`suspend`

  Suspend the sound server.

`status`

  Display sound server status information.

`terminate`

  Terminate the sound server. This may confuse and/or crash any applications that are currently using it.

`autosuspend` `seconds`

  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.

`networkbuffers` `n`

  Set the size of the network buffers to be a factor of `n` times the default size.

`volume` [volume]

  Sets volume scaling for sound server audio output. The volume argument is a floating point value. With no argument the current volume is displayed.

`stereoeffect list`

  List all of the available stereo effect modules.

`stereoeffect insert [top|bottom]` name

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

`stereoeffect remove` id

  Removes the stereo effect with identifier id from the effects stack.

## artsplay

The artsplay 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 `wav` or `au`. 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.

## artsdsp

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.

When an application is run under &artsdsp; all accesses to the `/dev/dsp` audio device are intercepted and mapped into &arts; API calls. While the device emulation is not perfect, most applications work this way, albeit with some degradation in performance and latency.

The &artsdsp; command follows the format:

artsdsp [options] application arguments

The following options are recognized:

`-h`, `--help`

  Show brief help.

`-n` `--name` = name

  Use name to identify player to `artsd`.

`-m` `--mmap`

  Emulate memory mapping (&eg; for Quake).

`-v` `--verbose`

  Show parameters.

A typical invocation is:

``artsdsp` `-v` `-m` `realplay song.mp3``

Some applications work better with the `--mmap` 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.

## artscat

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:

artscat [ options ] [ filename ]

If no file name is specified, it reads standard input. The following options are supported:

`-r` `sampling rate`

  Set the sampling rate to use.

`-b` `bits`

  Set sample size to use (8 or 16).

`-c` `channels`

  Set number of channels (1 or 2).

`-h`

  Display command usage and exit.

## &artscontrol;

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 View menu you can select other functions:

FFT Scope

  Opens a window which shows a real-time spectrum analyzer style display.

Audio Manager

  Displays active sound sources and allows you to connect them to any of the available busses.

aRts Status

  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.

Midi Manager

  Shows active &MIDI; inputs and outputs and allows you to make connections [TODO: Does this work yet? Need more detail].

FreeVerb

  Connects a FreeVerb reverb effect to the stack of &arts; output effects and allows you to control the effect parameters graphically.

Leds-like volume display

  Changes the volume indicators in the main window to use a colored LED display format instead of progress bars.

## artsc-config

This is a utility to assist developers using the &arts; C API. 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:

`--cflags`

  Displays the compiler flags needed when compiling with the &arts; C API.

`--libs`

  Displays the linker flags needed when linking with the &arts; C API.

--version

  Displays the version of the `artsc-config` command.

Typical output from the command is shown below:

    % artsc-config --cflags
    -I/usr/local/kde2/include/artsc
    % artsc-config --libs
    -L/usr/local/kde2/lib -ldl -lartsc -DPIC -fPIC -lpthread
    % artsc-config --version
    0.9.5

You could use this utility in a make file using a rule such as:

    artsc: artsc.c
            gcc `artsc-config --cflags` -o artsc artsc.c `artsc-config --libs`

## &mcopidl;

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:

mcopidl [ options ] filename

The valid options are:

`-I` `directory`

  Search in `directory` for includes.

`-e` `name`

  Exclude a struct, interface, or enum type `name` from code generation.

`-t`

  Also create `.mcoptype`/`.mcopclass` files containing type information for the &IDL; file.

More information about &MCOP; and &IDL; is covered in the section Interfaces and &IDL;.