# The &arts; Handbook

Stefan
Westerfeld

    stefan@space.twc.de

Jeff
Tranter

    tranter@kde.org

1999-2001
Stefan Westerfeld & Jeff Tranter
&FDLNotice;
04/01/2001
1.0.8

This handbook describes &arts;, the Analog Real-time Synthesizer.

aRts
artsbuilder
synthesizer
multimedia
structure
music
sound
KDE

## Introduction

### What is &arts;?

The Analog Real-Time Synthesizer, or &arts;, is a modular system for synthesizing sound and music on a digital computer. Using small building blocks called modules, the user can easily build complex audio processing tools. Modules typically provide functions such as sound waveform generators, filters, audio effects, mixing, and playback of digital audio in different file formats.

The artsd sound server mixes audio from several sources in real time, allowing multiple sound applications to transparently share access to sound hardware.

Using MCOP, the Multimedia Communication Protocol, multimedia applications can be network transparent, authenticated for security, and cross-platform using interfaces defined in a language-independent way using IDL. Support is also provided for non &arts;-aware legacy applications. As a core component of the &kde; 2 desktop environment, &arts; provides the basis for the &kde; multimedia architecture, and will in future support more media types including video. Like &kde;, &arts; runs on a number of operating systems, including &Linux; and BSD variants. It can also be used independently of &kde;.

### Using This Manual

This manual is intended to provide comprehensive documentation on &arts; for users at different skill levels. Depending on whether you are a casual user of multimedia applications that make use of &arts; or a multimedia application developer, you may want to take different paths through the manual.

It is suggested that you first read the Downloading and Building &arts; chapter if you need to get &arts; initially installed and running. If you already have a working system, likely bundled with your operating system distribution, you may choose to skip this section.

You should then read the sections in the &arts; Tools chapter, especially artsd, artscontrol, artsshell, and artsdsp. This will help you make the most effective use of &arts;.

If you are interested in going further with &arts;, read the chapter on artsbuilder and go through the tutorial. This should give you an appreciation of the powerful capabilities of &arts; and the provided modules that can be used without the need to be a programmer.

If you want to know more about the internals of &arts;, either to develop multimedia applications or extend &arts; itself, read some or all of the chapter &arts; in Detail. This should give you an understanding of all of the concepts that are prerequisites to &arts; software development.

If you are interested specifically in the MIDI capabilities of &arts;, you should read the chapter on MIDI.

If you want to develop &arts;-aware multimedia applications, the &arts; Application Programming Interfaces chapter covers the different APIs in detail.

If you want to extend &arts; by creating new modules, read the &arts; Modules chapter.

If you are modifying an existing application to run under &arts;, read the chapter on Porting Applications to &arts;.

You you can find out how to help contribute to the &arts; project in the Contributing to &arts; chapter, read about upcoming &arts; development in the chapter on Future Work, and find links to more information in the References section.

We have also rounded out the manual with some additional material, including answers to frequently asked questions, a list of contributors, the details on aRts copyright and licensing, and some background material on digital audio and MIDI. A glossary of terms is also included.

This manual is still very much a work in progress. You are welcome to contribute by writing portions of it, but if you wish to do so, contact Jeff Tranter tranter@kde.org first to avoid duplication of effort.

### History

In late 1997 Stefan Westerfeld started working on a real-time, modular system for sound synthesis. The code initially ran on a PowerPC system running &AIX;. This first implementation was quite simple but supported a full-featured flow system that was able to do such things as play MP3 files and pipe audio streams through effects modules.

The next step was to implement a GUI so that modules could be manipulated graphically. Stefan had had some good experience using &kde;, so that was chosen as the GUI toolkit, (knowing that it might be necessary to do a Gnome/Gtk+ version as well) and this later led to using &Linux; as the main development platform. Originally named ksynth, the project was renamed &arts; and the pace of development accelerated. The project at this stage was quite complete, with a CORBA-based protocol, dozens of modules, a graphical module editing tool, C and C++ APIs, documentation, utilities, and a mailing list and web site with a small group of developers. The project had come a long way after only a little more than a year of development.

As the &kde; team started planning for &kde; 2.0, it became clear that &kde; needed a more powerful infrastructure for sound and other streaming media. It was decided to adapt &arts;, as it was a good step in this direction with a proven architecture. Much new development effort went into this new version of &arts;, most notably the replacement of the CORBA code with an entirely new subsystem, MCOP, optimized for multimedia. Version 0.4 of &arts; was included in the &kde; 2.0 release.

Work continues on &arts;, improving performance and adding new functionality. It should be noted that even though &arts; is now a core component of &kde;, it can be used without &kde;, and is also being used for applications that go beyond traditional multimedia. The project has attracted some interest from the Gnome team, opening up the possibility that it may someday become the standard multimedia architecture for &UNIX; desktop systems.

## &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 &kcontrol; 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
    -u

    -a audiomethod
    -r sampling rate
    -b bits
    -d
    -D devicename
    -F fragments
    -S size

    -h
    -A
    -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.

`-l level`

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

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 <systemitem <!-- DocBook 4.1: class="username" --> >root) and then executes `artsd` as a non-root user.

### 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

    suspend
    status

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

### 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 (&ie; 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 <replaceable parameter>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.

## &artsbuilder;

### Overview

First of all, when trying to run &artsbuilder; , you should also be running the sound server (&artsd;). Usually, when you use &kde; 2.1, this should already be the case. If not, you can configure the automatic sound server startup under KControl Sound Sound Server.

When you are running &arts;, it always runs small modules. &artsbuilder; is a tool to create new structures of small connected modules. You simply click the modules inside the grid. To do so, choose them from the Modules menu, and then click somewhere in the green-grey plane.

Modules usually have ports (where usually audio signals are flowing in or out). To connect two ports, click on the first, which causes it to turn orange, and then click on the second. You can only connect an input port (on the upper side of a module) with an output port (on the lower side of a module). If you want to assign a fixed value to a port (or disconnect it), do so by double clicking on the port.

### Tutorial

#### Step 1

Start artsbuilder.

You need a Synth&lowbar;AMAN&lowbar;PLAY-module to hear the output you are creating. So create a Synth&lowbar;AMAN&lowbar;PLAY-module by selecting Modules Synthesis SoundIO Synth&lowbar;AMAN&lowbar;PLAY and clicking on the empty module space. Put it below the fifth line or so, because we'll add some stuff above.

The module will have a parameter "title" (leftmost port), and "autoRestoreID" (besides the leftmost port) for finding it. To fill these out, doubleclick on these ports, select constant value and type "tutorial" in the edit box. Click okay to apply.

Hit File/Execute structure. You will hear absolutely nothing. The play module needs some input yet... ;) If you have listened to the silence for a while, click okay and go to Step 2

#### Step 2

Create a Synth&lowbar;WAVE&lowbar;SIN module (from Modules Synthesis Waveforms ) and put it above the Synth&lowbar;AMAN&lowbar;PLAY module. (Leave one line space in between). As you see, it produces some output, but requires a "pos" as input. First lets put the output to the speakers. Click on the "out" port of the Synth&lowbar;WAVE&lowbar;SIN and then on the "left" port of Synth&lowbar;AMAN&lowbar;PLAY. Voila, you have connected two modules.

All oscillators in aRts don't require a frequency as input, but a position in the wave. The position should be between 0 and 1, which maps for a standard Synth&lowbar;WAVE&lowbar;SIN object to the range 0..2*pi. To generate oscillating values from a frequency, a Synth&lowbar;FREQUENCY modules is used.

Create a Synth&lowbar;FREQUENCY module (from Modules Synthesis Oscillation & Modulation ) and connect it's "pos" output to the "pos" input of your Synth&lowbar;WAVE&lowbar;SIN. Specify the frequency port of the FREQUENCY generator as constant value 440.

Hit File/Execute structure. You will hear a sinus wave at 440 Hz on one of your speakers. If you have listened to it for a while, click okay and go to Step 3.

#### Step 3

Ok, it would be nicer if you would hear the sin wave on both speakers. Connect the right port of Synth&lowbar;PLAY to the outvalue of the Synth&lowbar;WAVE&lowbar;SIN as well.

Create a Synth&lowbar;SEQUENCE object (from Modules Synthesis Midi & Sequencing ). It should be at the top of the screen. If you need more room you can move the other modules by selecting them (to select multiple modules use Shift), and dragging them around.

Now connect the frequency output of Synth&lowbar;SEQUENCE to the frequency input of the Synth&lowbar;FREQUENCY module. Then specify the sequence speed as constant value 0.13 (the speed is the leftmost port).

Now go to the rightmost port (sequence) of Synth&lowbar;SEQUENCE and type in as constant value A-3;C-4;E-4;C-4; this specifies a sequence. More to that in the Module Reference.

Note: Synth&lowbar;SEQUENCE really needs a sequence and the speed. Without that you'll perhaps get core dumps.

Hit File/Execute structure. You will hear a nice sequence playing. If you have enjoyed the feeling, click okay and go to Step 4.

#### Step 4

Create a Synth&lowbar;PSCALE module (from Modules Synthesis Envelopes ). Disconnect the outvalue of the SIN wave by doubleclicking it and choosing "not connected". Connect

- The SIN outvalue to the PSCALE invalue

- The PSCALE outvalue to the AMAN_PLAY left

- The PSCALE outvalue to the AMAN_PLAY right

- The SEQUENCE pos to the PSCALE pos

Finally, set the PSCALE top to some value, for instance 0.1.

How that works now: The Synth&lowbar;SEQUENCE gives additional information about the position of the note it is playing right now, while 0 means just started and 1 means finished. The Synth&lowbar;PSCALE module will scale the audio stream that is directed through it from a volume 0 (silent) to 1 (original loudness) back to 0 (silent). According to the position. The position where the peak should occur can be given as pos. 0.1 means that after 10&percnt; of the note has been played, the volume has reached its maximum, and starts decaying afterwards.

Hit File/Execute structure. You will hear the sequence with scaled notes. If you have enjoyed the feeling, click okay and go to Step 5.

#### Step 5: Starting to beam data around ;)

Start another artsbuilder

Put a Synth&lowbar;AMAN&lowbar;PLAY into it, configure it to a sane name. Put a Synth&lowbar;BUS&lowbar;DOWNLINK into it and

- set Synth&lowbar;BUS&lowbar;DOWNLINK bus to audio (that is just a name, call it fred if you like)

- connect Synth&lowbar;BUS&lowbar;DOWNLINK left to Synth&lowbar;AMAN&lowbar;PLAY left

- connect Synth&lowbar;BUS&lowbar;DOWNLINK right to Synth&lowbar;AMAN&lowbar;PLAY right

Start executing the structure. As expected, you hear nothing, ... not yet

Go back to the structure with the Synth&lowbar;WAVE&lowbar;SIN stuff and replace the Synth&lowbar;AMAN&lowbar;PLAY module by an Synth&lowbar;BUS&lowbar;UPLINK, and configure the name to audio (or fred if you like). Deleting modules works with selecting them and choosing edit/delete from menu (or pressing the del key).

Hit File Execute structure. You will hear the sequence with scaled notes, transported over the bus.

If you want to find out why something like this can actually be useful, click okay (in the artsbuilder that is executing the Synth&lowbar;SEQUENCE stuff, you can leave the other one running) and go to Step 6.

#### Step 6: Beaming for advanced users

Choose File/Rename structure from the menu of the artsbuilder which contains the Synth&lowbar;SEQUENCE stuff, and call it tutorial. Hit okay.

Choose File/Save

Start yet another artsbuilder and choose File/Load, and load the tutorial again.

Now you can hit File/Execute structure in both artsbuilders having that structure. You'll now hear two times the same thing. Depending on the time when you start it it will sound more or less nice.

Another thing that is good to do at this point in time is: start noatun, and play some mp3. Start artscontrol. Go to View View audio manager. What you will see is noatun and your "tutorial" playback structure playing something. The nice thing you can do is this: doubleclick on noatun. You'll now get a list of destinations. And see? You can assign noatun to send it's output via the audio bus your tutorial playback structure provides.

#### Step 7: Midi synthesis

Finally, now you should be able to turn your sin wave into an real instrument. This only makes sense if you have something handy that could send midi events to arts. I'll describe here how you can use some external keyboard, but a midibus aware sequence like Brahms will work as well.

First of all, clean up on your desktop until you only have one artsbuilder with the sine wave structure running (not executing). Then, three times go to Ports Create IN audio signal, and three times to Ports Create OUT audio signal. Place the ports somewhere.

Finally, go to Ports Change positions and names and call the ports frequency, velocity, pressed, left, right, done.

Finally, you can delete the Synth&lowbar;SEQUENCE module, and rather connect connect the frequency input port of the structure to the Synth&lowbar;FREQUENCY frequency port. Hm. But what do do about pos?

We don't have this, because with no algorithm in the world, you can predict when the user will release the note he just pressed on the midi keyboard. So we rather have a pressed parameter instead that just indicates wether the user still holds down the key. (pressed = 1: key still hold down, pressed = 0: key released)

That means the Synth&lowbar;PSCALE object also must be replaced now. Plug in a Synth&lowbar;ENVELOPE&lowbar;ADSR instead (from Modules Synthesis Envelopes ). Connect

- The pressed structure input to the ADSR active

- The SIN outvalue to the ADSR invalue

- The ADSR outvalue to the left structure output

- The ADSR outvalue to the right structure output

Set the parameters attack to 0.1, decay to 0.2, sustain to 0.7, release to 0.1.

Another thing we need to think of is that the instrument structure somehow should know when it is ready playing and then be cleaned up, because otherwise it would be never stopped even if the note has been released. Fortunately, the ADSR envelope knows when the will be nothing to hear anymore, since it anyway scales the signal to zero at some point after the note has been released.

This is indicated by setting the done output to 1. So connect this to the done output of the structure. The structure will be removed as soon as done goes up to 1.

Rename your structure to instrument_tutorial (from File Rename structure. Then, save it using save as (the default name offered should be instrument_tutorial now).

Start artscontrol, and go to View Midi Manager, and choose Add aRts Synthesis Midi Output. Finally, you should be able to select your instrument (tutorial) here.

Open a terminal and type `midisend`. You'll see that midisend and the instrument are listed now in the aRts midi manager. After selecting both and hitting connect, we're finally done. Take your keyboard and start playing (of course it should be connected to your computer).

#### Suggestions

You now should be able to work with arts. Here are a few tips what you could try to improve with your structures now:

- Try using other things than a SIN wave. When you plug in a TRI wave, you will most likely think the sound is not too nice. But try appending a SHELVE&lowbar;CUTOFF filter right after the TRI wave to cut the frequencies above a certain frequency (try something like 1000 Hz, or even better two times the input frequency or input frequency+200Hz or something like that).

- Try using more than one oscillator. Synth&lowbar;XFADE can be used to cross fade (mix) two signals, Synth&lowbar;ADD to add them.

- Try setting the frequencies of the oscillators to not exactly the same value, that gives nice oscillations.

- Experiment with more than one envelope.

- Try synthesizing instruments with different output left and right.

- Try postprocessing the signal after it comes out the bus downlink. You could for instance mix a delayed version of the signal to the original to get an echo effect.

- Try using the velocity setting (its the strength with which the note has been pressed, you could also say volume). The special effect is always when this not only modifies the volume of the resulting signal, but as well the sound of the instrument (for instance the cutoff frequency).

- ...

If you have created something great, please consider providing it for the aRts web page. Or for inclusion into the next release.

### Examples

Artsbuilder comes with several examples, which can be opened through File Open Example... . Some of them are in the directory, some of them (which for some reason don't work with the current release) are left in the todo directory.

The examples fall into several categories:

- Standalone examples illustrating how to use each of the built-in arts modules (named example_*.arts). These typically send some output to a sound card.

- Instruments built from lower level arts modules (named instrument_*.arts). These following a standard convention for input and output ports so they can be used by the midi manager in artscontrol.

- Templates for creating new modules (names template_*.arts).

- Effects which can be used as reusable building blocks (named effect_*.arts) [ all in todo ]

- Mixer elements used for creating mixers, including graphical controls (named mixer_element_*.arts). [ all in todo ]

- Miscellaneous modules that don't fit into any of the above categories.

Detailed Description Of Each Module:

example_stereo_beep.arts

  Generates a 440Hz sine wave tone in the left channel and an 880Hz sine wave tone in the right channel, and sends it to the sound card output. This is referenced in the aRts documentation.

example_sine.arts

  Generates a 440 Hz sine wave.

example_pulse.arts

  Generates a 440 Hz pulse wave with a 20% duty cycle.

example_softsaw.arts

  Generates a 440 Hz sawtooth wave.

example_square.arts

  Generates a 440 Hz square wave.

example_tri.arts

  Generates a 440 Hz triangle wave.

example_noise.arts

  Generates white noise.

example_dtmf1.arts

  Generates a dual tone by producing 697 and 1209 Hz sine waves, scaling them by 0.5, and adding them together. This is the DTMF tone for the digit "1" on a telephone keypad.

example_atan_saturate.arts

  Runs a triangle wave through the atan saturate filter.

example_autopanner.arts

  Uses an autopanner to pan a 400 Hz sine wave between the left and right speakers at a 2 Hz rate.

example_brickwall.arts

  Scales a sine wave by a factor of 5 and then runs it through a brickwall limiter.

example_bus.arts

  Downlinks from a bus called "Bus" and uplinks to the bus "out_soundcard" with the left and right channels reversed.

example_cdelay.arts

  Downlinks from a bus called "Delay", uplinks the right channel through a 0.5 second cdelay, and the left channel unchanged. You can use artscontrol to connect the effect to a sound player and observe the results.

example_delay.arts

  This is the same as example_cdelay but used the delay effect.

example_capture_wav.arts

  This uses the Synth_CAPTURE_WAV to save a 400 Hz sine wave as a wav file. Run the module for a few seconds, and then examine the file created in /tmp. You can play the file with a player such as kaiman.

example_data.arts

  This uses the Data module to generate a constant stream of the value "3" and sends it to a Debug module to periodically display it. It also contains a Nil module, illustrating how it can be used to do nothing at all.

example_adsr.arts

  Shows how to create a simple instrument sound using the Envelope Adsr module, repetitively triggered by a square wave.

example_fm.arts

  This uses the FM Source module to generate a 440 Hz sine wave which is frequency modulated at a 5 Hz rate.

example_freeverb.arts

  This connects the Freeverb effect from a bus downlink to a bus outlink. You can use artscontrol to connect the effect to a sound player and observe the results.

example_flanger.arts

  This implements a simple flanger effect (it doesn't appear to work yet, though).

example_moog.arts

  This structure combines the two channels from a bus into one, passes it though the Moog VCF filter, and sends it out the out_soundcard bus.

example_pitch_shift.arts

  This structure passes the left channel of sound card data through the Pitch Shift effect. Adjust the speed parameter to vary the effect.

example_rc.arts

  This structure passes a white noise generator though an RC filter and out to the sound card. By viewing the FFT Scope display in artscontrol you can see how this varies from an unfiltered noise waveform.

example_sequence.arts

  This demonstrates the Sequence module by playing a sequence of notes.

example_shelve_cutoff.arts

  This structure passes a white noise generator though a Shelve Cutoff filter and out to the sound card. By viewing the FFT Scope display in artscontrol you can see how this varies from an unfiltered noise waveform.

example_equalizer.arts

  This demonstrates the Std_Equalizer module. It boosts the low and high frequencies by 6 dB.

example_tremolo.arts

  This demonstrates the Tremolo effect. It modulates the left and right channels using a 10 Hz tremolo.

example_xfade.arts

  This example mixes 440 and 880 Hz sine waves using a cross fader. Adjust the value of the cross fader's percentage input from -1 to 1 to control the mixing of the two signals.

example_pscale.arts

  This illustrates the Pscale module (I'm not sure if this is a meaningful example).

example_play_wav.arts

  This illustrates the Play Wave module. You will need to enter the full path to a .wav file as the filename parameter.

example_multi_add.arts

  This shows the Multi Add module which accepts any number of inputs. It sums three Data modules which produce inputs of 1, 2, and 3, and displays the result 6.

## &arts; in Detail

### Architecture

### Modules & Ports

The idea of aRts is, that synthesis can be done using small modules, which only do one thing, and then recombine them in complex structures. The small modules normally have inputs, where they can get some signals or parameters, and outputs, where they produce some signals.

One module (Synth&lowbar;ADD) for instance just takes the two signals at it's input and adds them together. The result is available as output signal. The places where modules provide their input/output signals are called ports.

### Structures

A structure is a combination of connected modules, some of which may have parameters coded directly to their input ports, others which may be connected, and others, which are not connected at all.

What you can do with ArtsBuilder is describing structures. You describe, which modules you want to be connected with which other modules. When you are done, you can save that structure description to a file, or tell Arts to create such a structure you described (Execute).

Then you'll probably hear some sound, if you did everything the right way.

### Busses

Busses are dynamically built connections that transfer audio. Basically, there are some uplinks and some downlinks. All signals from the uplinks are added and send to the downlinks.

Busses as currently implemented operate in stereo, so you can only transfer stereo data over busses. If you want mono data, well, transfer it only over one channel and set the other to zero or whatever. What you need to to, is to create one or more Synth&lowbar;BUS&lowbar;UPLINK objects and tell them a bus name, to which they should talk (e.g. "audio" or "drums"). Simply throw the data in there.

Then, you'll need to create one or more Synth&lowbar;BUS&lowbar;DOWNLINK objects, and tell them the bus name ("audio" or "drums" ... if it matches, the data will get through), and the mixed data will come out again.

The uplinks and downlinks can reside in different structures, you can even have different Artsbuilders running and start an uplink in one and receive the data from the other with a downlink.

What is nice about busses is, that they are fully dynamic. Clients can plug in and out on the fly. There should be no clicking or noise as this happens.

(Of course, you should not plug out a client playing a signal, since it will probably not be a zero level when plugged out the bus, and then it will click.)

### GUI Elements

GUI elements are currently in the experimental state. However, this section will describe what is supposed to happen here, so if you are a developer, you will be able to understand how &arts; will deal with GUIs in the future. There is some code there already, too.

GUI elements should be used to allow synthesis structures to interact with the user. In the simplest case, the user should be able to modify some parameters of a structure directly (such as a gain factor which is used before the final play module).

In more complex settings, one could imagine the user modifying parameters of groups of structures and/or not yet running structures, such as modifying the ADSR envelope of the currently active midi instrument. Another thing would be setting the filename of some sample based instrument.

On the other hand, the user could like to monitor what the synthesizer is doing. There could be oscilloscopes, spectrum analyzers, volume meters and "experiments" that figure out the frequency transfer curve of some given filter module.

Finally, the GUI elements should be able to control the whole structure of what is running inside Arts and how. The user should be able to assign instruments to midi channels, start new effect processors, configure his main mixer pult (which is built of aRts structures itself) to have one channel more and use another strategy for its equalizers.

You see - the GUI elements should bring all possibilities of the virtual studio aRts should simulate to the user. Of course, they should also gracefully interact with midi inputs (such as sliders should move if they get midi inputs which also change just that parameter), and probably even generate events themselves, to allow the user interaction to be recorded via sequencer.

Technically, the idea is to have an IDL base class for all widgets (Arts::Widget), and derive a number of commonly used widgets from there (like Arts::Poti, Arts::Panel, Arts::Window, ...). Then, one can implement these widgets using a toolkit, for instance Qt or Gtk. Finally, effects should build their GUIs out of existing widgets. For instance, a freeverb effect could build it's GUI out of five Arts::Poti thingies and a Arts::Window. So IF there is a Qt implementation for these base widgets, the effect will be able to display itself using Qt. If there is Gtk implementation, it will also work for Gtk (and more or less look/work the same).

Finally, as we're using IDL here, artsbuilder (or other tools) will be able to plug GUIs together visually, or autogenerate GUIs given hints for parameters, only based on the interfaces. It should be relatively straight forward to write a "create GUI from description" class, which takes a GUI description (containing the various parameters and widgets), and creates a living GUI object out of it. Based on IDL and the &arts;/MCOP component model, it should be easy to extend the possible objects which can be used for the GUI just as easy as it is to add a plugin implementing a new filter to &arts;.

## MIDI

### Overview

The midi support in aRts can do a number of things. First of all, it allows communication between different pieces of software that produce or consume MIDI events. If you for instance have a sequencer and a sampler that are both aRts aware, aRts can send the MIDI events from the sequencer to the sampler.

On the other hand, aRts can also help applications to interact with the hardware. If a piece of software (for instance the sampler) works together with aRts, it will be able to receive the MIDI events from an external MIDI keyboard as well.

Finally, aRts makes a great modular synthesizer. It is designed to do exactly this. So you can build instruments out of small modules using artsbuilder, and then use these instruments to compose or play music. Synthesis does not necessarily mean pure synthesis, there are modules you can use to play samples. So aRts can be a sampler, synthesizer, and so on, and being fully modular, it is very easy to extend, very easy to experiment with, powerful and flexible.

### The Midi Manager

The central component in aRts that keeps track which applications are connected and how midi events should be passed between them is the midi manager. To see or influence what it does, start artscontrol. Then, choose View View Midi Manager over the menu.

On the left side, you will see Midi Inputs. There, all objects that produce midi events, such as an external midi port which sends data from a connected midi keyboard, a sequencer which plays a song and so on will be listed. On the right side, you will see Midi Outputs. There, all things that consume midi events, such as a simulated sampler (as software), or the external midi port where your hardware sampler outside your computer is connected will be listed. New applications, such as sequencers and so on will register themselves, so the list will be changing over time.

You can connect inputs and outputs if you mark the input on the left side and the output on the right side, and choose Connect with the button below. Disconnect works the same. You will see what is connected as small lines between the inputs and outputs, in the middle of the window. Note that you can connect one sender to more than one receiver (and the other way round).

Programs (like the Brahms sequencer) will add themselves when they start and be removed from the list when they are terminated. But you can also add new things in the Add menu:

System Midi Port (OSS)

  This will create a new aRts object that talks to an external midi port. As external midi ports can do both, send and receive data, choosing this option will add a midi input and a midi output. Under linux, you should either have an OSS (or OSS/Free, the thing that comes with your linux kernel) or an ALSA driver for your soundcard installed, to make it work. It will ask for the name of the device. Usually, this is /dev/midi or /dev/midi00. However, if you have more than one midi device or a midi loopback driver installed, there might be more choices. To see information about your midi ports, start the KDE Control Center, and choose Information Sound.

aRts Synthesis Midi Output

  This will add a new midi output with an aRts synthesis instrument. If you choose the menu item, a dialog will pop up, and allow you to choose an instrument. You can create new instruments using artsbuilder. All .arts-files with a name that starts with "instrument_" will appear here.

### Using &arts; & Brahms

Actually, getting started is quite easy. You need a KDE2.1-aware version of Brahms, which can be found in the kmusic CVS module. There is also information on how to get Brahms on the aRts Homepage in the Download section.

When you start it, it will show up in the midi manager. If you want to do synthesis, simply add a synthesis midi instrument via Add aRts Synthesis Midi Output. Choose an instrument (for instance organ2). Connect them using the Connect button. Finally, you can start composing in Brahms, and the output will be synthesized with aRts. It is usually a good idea to have the artscontrol window open, and see that the volume is not too loud (quality gets bad when the bars hit the upper limit). Now you can start working on a new aRts demosong, and if you are done, you can get it published on aRts-project.org ;-).

### midisend

Midisend is a small application that will allow you to send midi events from the shell. It will register as client like all other applications. The most simple way to use it is to do

    &percnt; midisend -f /dev/midi00

which will achieve about the same as adding a system midi port in artscontrol (not quite, because midisend only sends events). The difference is that it is easy for instance to start midisend on different computers (and like that, use network transparency). It is also possible to make midisend send data from stdin, which you can use to pipe data from non-aRts-aware applications to aRts, like this

    &percnt; applicationwhichproducesmidieventsonstdout | midisend -f -

### Creating Instruments

The way &arts; does midi synthesis is this: you have a structures which has some input ports, where it gets the frequency, velocity (volume) and a parameter which indicates whether the note is still pressed. The structure should now synthesize exactly that note with that volume, and react on the pressed parameter (where pressed = 1 means the user still holds down that key and pressed = 0 means the user has released that key).

When midi events arrive, &arts; will create new structures for the notes as needed, give them the parameters, and clean them up once they are done.

To create and use such a structure, you should do the following:

- To get started, the most convenient way is to open template_Instrument.arts in artsbuilder. This can be achieved by using File Open Example... and choosing template_Instrument in the file selector. This will give you an empty structure with the required parameters, which you only need to "fill out".

- To process the pressed parameter, it is convenient to use Synth&lowbar;ENVELOPE&lowbar;ADSR, or, in case of playing some drum wav, just play it anyway, and ignore the pressed parameter.

- The structure should indicate when it is no longer needed on the "done" output. If done is 1, &arts; assumes that it can delete the structure. Conveniently, the ADSR envelope provides a parameter when it is done, so you just need to connect this to the done output of the structure.

- You should rename your structure to some name starting with instrument_, like instrument_piano.arts - you should save the file under the same name, in your $HOME/arts/structures directory (which is where artsbuilder wants to save files normally).

- Finally, once you saved it, you will be able to use it with artscontrol in the midi manager .

- Oh, and of course your structure should play the audio data it generates to the left and right output of the structure, which will then be played via audio manager (you can see that in artscontrol), so that you finally can hear it (or postprocess it with effects).

A good way to learn how to do instruments is to open an existing instrument via File Open Example and see how it works ;)

### Mapped Instruments

Mapped instruments are instruments, that behave differently depending on the pitch, the program, the channel or the velocity. You could for instance build a piano of 5 octaves, using one sample for each octave (pitchshifting it accordingly). That sounds a whole lot better than only using one sample.

You could also build a drum map, that plays one specific drum sample per key.

Finally, it is very useful if you put quite some different sounds into one mapped instrument on different programs. That way, you can use your sequencer, external keyboard or other midi source to switch between the sounds without having to tweak aRts as you work. A good example for this is the instrument "arts_all", which just puts together all instruments that come with aRts in one map. That way, you just need to setup once in aRtscontrol to use this "instrument", and then, you can compose a whole song in a sequencer without ever bothering about aRts. Need another sound? Simply change the program in the sequencer, and aRts will give you another sound.

Creating such maps is pretty straightforward. You just need to create a textfile, and write rules which look like this:

    ON [ conditions ...] DO structure=somestructure.arts

The conditions could be one or more than one of the following

pitch

  The pitch that is being played. You would use this if you want to split your instrument depending on the pitch. In our initial examples, a piano which uses different samples for different octaves would use this as condition. You can specify a single pitch, like pitch=62 or a range of pitches, like pitch=60-72. The possible pitches are between 0 and 127.

program

  The program that is active on the channel that the note is being sent on. Usually, sequencers let you choose the "instrument" via the program setting. Single programs or ranges are allowed, that is program=3 or program=3-6. The possible programs are between 0 and 127.

channel

  The channel that that the note is being sent on. Single channels or ranges are allowed, that is channel=0 or channel=0-8. The possible channels are between 0 and 15.

velocity

  The velocity (volume) that that the note has. Single velocities (who would use that?) or ranges are allowed, that is velocity=127 or veclocity=64-127. The possible velocities are between 0 and 127.

A complete example for a map would be (this is taken from the current instrument_arts_all.arts-map):

    ON program=0 DO structure=instrument_tri.arts
    ON program=1 DO structure=instrument_organ2.arts
    ON program=2 DO structure=instrument_slide1.arts
    ON program=3 DO structure=instrument_square.arts
    ON program=4 DO structure=instrument_neworgan.arts
    ON program=5 DO structure=instrument_nokind.arts
    ON program=6 DO structure=instrument_full_square.arts
    ON program=7 DO structure=instrument_simple_sin.arts
    ON program=8 DO structure=instrument_simple_square.arts
    ON program=9 DO structure=instrument_simple_tri.arts
    ON program=10 DO structure=instrument_slide.arts
    ON program=11 pitch=60 DO structure=instrument_deepdrum.arts
    ON program=11 pitch=61 DO structure=instrument_chirpdrum.arts

As you see, the structure is choosen depending on the program. On program 11, you see a "drum map" (with two entries), which would play a "deepdrum" on C-5 (pitch=60), and a "chirpdrum" on C#5 (pitch=61).

To make map files automatically appear in artscontrol as choice for the instrument, they have to be called "instrument_something.arts-map" and reside either in your Home-Directory, under $HOME/arts/structures, or in the KDE directory under $KDEDIR/usr/local/kde/share/apps/artsbuilder/examples. Structures that are used by the map can either be given with an absolute path, or relative to the directory the map file resides in.

Extending the arts_all map or even making a complete general midi map for &arts; is a good idea for making &arts; easier to use out-of-the-box. Please consider contributing interesting instruments you make, so that they can be included in further version of &arts;.

## MCOP: Object Model and Streaming

### Overview

MCOP is the standard &arts; uses for:

- communication between objects

- network transparency

- describing object interfaces

- language independancy

One major aspect of MCOP is the interface description language, IDL, in which many of the &arts; interfaces and APIs are defined in a language independand way. To use IDL interfaces from C++, is compiled by the IDL compiler into C++ code. When you implement an interface, you derive from the skeleton class the IDL compiler has generated. When you use an interface, you do so using a wrapper. This way, MCOP can use a protocol if the object you are talking to is not local - you get network transparency.

This chapter is supposed to describe the basic features of the object model that results from the use of MCOP, the protocol, how do use MCOP in C++ (language binding), and so on.

### Interfaces and IDL

### Attribute change notifications

Attribute change notifications are a way to know when an attribute changed. They are a bit comparable with &Qt;'s or Gtk's signals and slots. For instance, if you have a GUI element, a slider, which configures a number between 0 and 100, you will usually have an object that does something with that number (for instance, it might be controlling the volume of some audio signal). So you would like that whenever the slider is moved, the object which scales the volume gets notified. A connection between a sender and a receiver.

MCOP deals with that by being able to providing notifications when attributes change. Whatever is declared as attribute in the IDL, can emit such change notifications, and should do so, whenever it is modified. Whatever is declared as attribute can also receive such change notifications. So for instance if you had two IDL interfaces, like these:

     interface Slider {
             attribute long min,max;
             attribute long position;
     };
     interface VolumeControl : Arts::StereoEffect {
         attribute long volume; // 0..100
     };

You can connect them using change notifications. It works using the normal flowsystem connect operation. In this case, the C++ code to connect two objects would look like this

    #include <connect.h>
    using namespace Arts;
    [...]
    connect(slider,"position_changed",volumeControl,"volume");

As you see, each attribute offers two different streams, one for sending the change notifications, called `attributename_changed`,

and one for receiving change notifications, called `attributename`.

It is important to know that change notifications and asynchronous streams are compatible. They are also network transparent. So you can connect a change notification of a float attribute of a GUI widget has to an asynchronous stream of a synthesis module running on another computer. This of course also implies that change notifications are not synchronous, this means, that after you have sent the change notification, it may take some time until it really gets received.

#### Sending change notifications

When implementing objects that have attributes, you need to send change notifications whereever an attribute changes. The code for doing this looks like this:

     void KPoti_impl::value(float newValue)
     {
         if(newValue != _value)
         {
             _value = newValue;
             value_changed(newValue); // <- send change notification
         }
     }

It is strongly recommended to use code like this for all objects you implement, so that change notifications can be used by other people. You should however void sending notifications too often, so if you are doing signal processing, it is probably the best if you keep track when you sent your last notification, so that you don't send one with every sample you process.

#### Applications for change notifications

It will be especially useful to use change notifications in conjunction with scopes (things that visualize audio data for instance), gui elements, control widgets, and monitoring. Code using this is in kdelibs/arts/tests, and in the experimental artsgui implementation, which you can find under `kdemultimedia/arts/gui`.

## &arts; Application Programming Interfaces

### Overview

aRts is not only a piece of software, it also provides a variety of APIs for a variety of purposes. In this section, I will try to describe the "big picture", a brief glance what those APIs are supposed to do, and how they interact.

There is one important distinction to make: most of the APIs are language and location independant because they are specified as mcopidl. That is, you can basically use the services they offer from any language, implement them in any language, and you will not have to care whether you are talking to local or remote objects. Here is a list of these first:

core.idl

  Basic definitions that form the core of the MCOP functionality, such as the protocol itself, definitions of the object, the trader, the flow system and so on.

artsflow.idl

  These contain the flow system you will use for connecting audio streams, the definition of Arts::SynthModule which is the base for any interface that has streams, and finally a few useful audio objects

kmedia2.idl

  Here, an object that can play a media, Arts::PlayObject gets defined. Media players such as the KDE media player noatun will be able to play any media for which a PlayObject can be found. So it makes sense to implement PlayObjects for various formats (such as mp3, mpg video, midi, wav, ...) on that base, and there are a lot already.

soundserver.idl

  Here, an interface for the system wide sound server artsd is defined. The interface is called Arts::SoundServer, which implements functionality like accepting streams from the network, playing samples, creating custom other aRts objects and so on. Network transparency is implied due to the use of MCOP (as for everything else here).

artsbuilder.idl

  This module defines basic flow graph functionality, that is, combining simpler objects to more complex ones, by defining a graph of them. It defines the basic interface Arts::StructureDesc, Arts::ModuleDesc and Arts::PortDesc which contain a description of a structure, module, and port. There is also a way to get a "living network of objects" out of these connection and value descriptions, using a factory.

artsmidi.idl

  This module defines basic midi functionality, like objects that produce midi events, what is a midi event, an Arts::MidiManager to connect the producers and consumers of midi events, and so on. As always network transparency implied.

artsmodules.idl

  Here are various additional filters, oscillators, effects, delays and so on, everything required for real useful signal processing, and to build complex instruments and effects out of these basic building blocks.

artsgui.idl

  This cares about visual objects. It defines the basic type Arts::Widget from which all GUI modules derive. This will produce toolkit independency, and ... visual GUI editing, and serializable GUIs. Also, as the GUI elements have normal attributes, their values can be straight forward connected to some signal processing modules. (I.e. the value of a slider to the cutoff of a filter). As always: network transparent.

Where possible, aRts itself is implemented using IDL. On the other hand, there are some language specific APIs, using either plain C++ or plain C. It is usually wise to use IDL interfaces where possible, and the other APIs where necessary. Here is a list of language specific APIs:

KNotify, KAudioPlayer (included in libkdecore)

  These are convenience KDE APIs for the simple and common common case, where you just want to play a sample. The APIs are plain C++, Qt/KDE optimized, and as easy as it can get.

libartsc

  Plain C interface for the sound server. Very useful for porting legacy applications.

libmcop

  Here all magic for MCOP happens. The library contains the basic things you need to know for writing a simple MCOP application, the dispatcher, timers, iomanagement, but also the internals to make the MCOP protocol itself work.

libartsflow

  Besides the implementation of artsflow.idl, some useful utilities like sampling rate conversion.

libqiomanager

  Integration of MCOP into the Qt event loop, when you write Qt applications using MCOP.

### knotify

### kaudioplayer

### libkmid

### kmedia2

### sound server

### artsflow

### C API

#### Introduction

The &arts; C API was designed to make it easy to writing and port plain C applications to the &arts; sound server. It provides streaming functionality (sending sample streams to artsd), either blocking or non-blocking. For most applications you simply remove the few system calls that deal with your audio device and replace them with the appropriate &arts; calls.

I did two ports as a proof of concept: mpg123 and quake. You can get the patches from here. Feel free to submit your own patches to the maintainer of &arts; or of multimedia software packages so that they can integrate &arts; support into their code.

#### Quick Walkthrough

Sending audio to the sound server with the API is very simple:

1. include the header file using `#include <artsc.h>`

2. initialize the API with `arts_init()`

3. create a stream with `arts_play_stream()`

4. configure specific parameters with `arts_stream_set()`

5. write sampling data to the stream with `arts_write()`

6. close the stream with `arts_close_stream()`

7. free the API with `arts_free()`

Here is a small example program that illustrates this:

    #include <stdio.h>
    #include <artsc.h>

    int main()
    {
        arts_stream_t stream;
        char buffer[8192];
        int bytes;
        int errorcode;

        errorcode = arts_init();
        if (errorcode < 0)
        {
            fprintf(stderr, "arts_init error: %s\n", arts_error_text(errorcode));
            return 1;
        }

        stream = arts_play_stream(44100, 16, 2, "artsctest");

        while((bytes = fread(buffer, 1, 8192, stdin)) > 0)
        {
            errorcode = arts_write(stream, buffer, bytes);
            if(errorcode < 0)
            {
                fprintf(stderr, "arts_write error: %s\n", arts_error_text(errorcode));
                return 1;
            }
        }

        arts_close_stream(stream);
        arts_free();

        return 0;
    }

#### Compiling and Linking: artsc-config

To easily compile and link programs using the &arts; C API, the artsc-config utility is provided which knows which libraries you need to link and where the includes are. It is called using

    artsc-config --libs

to find out the libraries and

    artsc-config --cflags

to find out additional C compiler flags. The example above could have been compiled using the command line:

    cc -o artsctest artsctest.c `artsc-config --cflags` `artsc-config --libs`

    cc -o artsctest artsctest.c `artsc-config --cflags` `artsc-config --libs`

#### Library Reference

[TODO: generate the documentation for artsc.h using kdoc]

## &arts; modules

### Introduction

### Synthesis Modules Reference

#### Arithmetic + Mixing

##### Synth&lowbar;ADD

This adds two signals.

##### Synth&lowbar;MUL

This multiplies a signal by a factor. You can use this to scale signals down (0 < factor < 1) or up (factor > 1) or invert signals (factor < 0). Note that the factor may be a signal and don't has to be constant (e.g. envelope or real signal).

##### Synth&lowbar;MULTI&lowbar;ADD

This adds an arbitary number of signals. If you need to sum up the waveforms produces by four different oscillators, you for instance can connect all their outputs to one Synth&lowbar;MULTI&lowbar;ADD module. This is more efficient than using three Synth&lowbar;ADD modules.

##### Synth&lowbar;XFADE

This crossfades two signals. If the percentage input is -1, only the left signal is heard, if it is 1, only the right signal is heard. When it is 0, both signals a heard with the same volume.

This allows you to ensure that your signal stays in a well defined range. If you had two signals that were between -1 and 1 before crossfading, they will be in the same range after crossfading.

##### Synth&lowbar;AUTOPANNER

The opposite of a crossfader. This takes a mono signal and splits it into a stereo signal: It is used to automatically pan the input signal between the left and the right output. This makes mixes more lively. A standard application would be a guitar or lead sound.

Connect a LFO, a sine or saw wave for example to inlfo. and select a frequency between 0.1 and 5Hz for a traditional effect or even more for Special FX.

#### Busses

##### Synth&lowbar;BUS&lowbar;UPLINK

An uplink to a bus. Give signals to left and right, and the name of the bus where the data should go on the "bus" port. The combined signal from all uplinks with this name will appear on every downlink on that "bus".

##### Synth&lowbar;BUS&lowbar;DOWNLINK

Gets (the sum of) all data that is put to a certain bus (with the name you specify at the "bus" port).

#### Delays

##### Synth&lowbar;DELAY

This delays the input signal for an amount of time. The time specification must be between 0 and 1 for a delay between 0 seconds and 1 second.

This kind of delay may not be used in feedback structures. This is because it's a variable delay. You can modify it's length while it is running, and even set it down to zero. But since in a feedback structure the own output is needed to calculate the next samples, a delay whose value could drop to zero during synthesis could lead to a stall situation.

Use CDELAYs in that setup, perhaps combine a small constant delay (of 0.001 seconds) with a flexible delay.

You can also combine a CDELAY and a DELAY to achieve a variable length delay with a minimum value in a feedback loop. Just make sure that you have a CDELAY involved.

##### Synth&lowbar;CDELAY

This delays the input signal for an amount of time. The time specification must be between 0 and 1 for a delay between 0 seconds and 1 second. The delay is constant during the calculation, that means it can't be modified.

This saves computing time as no interpolation is done, and is useful for recursive structures. See description above (Synth&lowbar;DELAY).

#### Envelopes

##### Synth&lowbar;ENVELOPE&lowbar;ADSR

This is a classic ADSR envelope which means you specify:

active

  whether the note is being pressed right now by the user

invalue

  the input signal

attack

  the time that should pass between the user presses the note and the signal reaching it's maximum amplitude (in seconds)

decay

  the time that should pass between the the signal reaching it's maximum amplitude and the signal going back to some constant level (in seconds)

sustain

  the constant level the signal is held at afterwards, until the user releases the note

release

  the time that should pass after the user has released the note until the signal is scaled down to zero (in seconds)

You'll get the scaled signal at outvalue. If the ASDR envelope is finished, it will set done to 1. You can use this to provide the "done" output of an instrument (which will make the instrument structure be deleted by the midi router object once the release phase is over).

##### Synth&lowbar;PSCALE

The Synth&lowbar;PSCALE module will scale the audio stream that is directed through it from a volume 0 (silent) to 1 (original loudness) back to 0 (silent). According to the position (get the position from Synth&lowbar;SEQUENCE). The position where the peak should occur can be given as pos.

Example: Setting top to 0.1 means that after 10&percnt; of the note has been played, the volume has reached its maximum, and starts decaying afterwards.

#### Effects

##### Synth&lowbar;FREEVERB

This is a reverb effect. In the current implementation, it is thought to pass a stereo signal through the reverb, and it will -add- it's reverb effect to the signal. (Note: this means that it can be used inside an StereoEffectStack as well). The input signal should be connected to (inleft, inright), the output signal will be (outleft, outright).

The parameters which you can configure are:

roomsize

  the size of the room which the reverb simulates (range: 0..1, where 1 is the largest possible room)

damp

  this specifies a filter which will make the simulated room absorb high frequencies (range 0..1, where 1 means absorb high frequencies quite agressive)

wet

  the amount of reverb-signal (that is, the amount of the signal that should be modified by the filters, resulting in a "wet", that is "reverb sound"

dry

  the amount of pure signal passed through, resulting in an echo (or combined delay) rather than reverb effect (range: 0..1)

width

  the amount of stereo-magic the reverb algorithm adds to the reverb effect, making the reverb sound wider in the stereo panorama (range: 0..1)

mode

  [ TODO: I think if mode is 1, the reverb holds the current image of the sound, whereas 0 is normal operation ]

##### Synth&lowbar;TREMOLO

The tremolo module modulates the amplitude according to a LFO-Wave. Traditionally you would use a sine wave but why limit yourself? What you get is a very intense effect that cuts through most arrangements because of its high dynamic range. The tremolo effect is still one of guitarists favourite effects although it's not as popular as in the 1960's.

[ TODO: currently this is implemented as invalue + abs(inlfo) - maybe it would make more sense to implement it as invalue * (1+inlfo*depth), where depth would be a parameter between 0..1 - decide this after KDE2.1 ; if you have a comment, send a mail to the aRts list ;). ]

##### Synth&lowbar;FX&lowbar;CFLANGER

A flanger is a time-varying delay effect. To make development of complex flanger effects simpler, this module is provided, which contains the core of a one-channel flanger.

It has the following ports:

invalue

  The signal which you want to process.

lfo

  Preferably a sine wave which modulates the delay time inside the flanger (-1 .. 1).

mintime

  The minimum value for the delay inside the flanger in milliseconds. Suggested values: try something like 1 ms. Please use values < 1000 ms.

maxtime

  The minimum value for the delay inside the flanger in milliseconds. Suggested values: try something like 5 ms. Please use values < 1000 ms.

outvalue

  The output signal. It is important that you mix that with the original (unflanged) signal to get the desired effect.

Hint: you can use this as a basis for a chorus effect.

#### Filters

##### Synth&lowbar;PITCH&lowbar;SHIFT

This pitch shifting effect changes the frequency of the input signal without affecting the speed. An application for this is for instance changing the pitch of your voice while you record (and replay) it in realtime

The speed parameter is the relative speed with which the signal will be replayed. So a speed of two would make it sound twice as high (i.e. an input frequency of 440 Hz would result in an output frequency of 880 Hz).

The frequency parameter is used internally to switch between different grains of the signal. It is tunable, and depending on your choice, the pitch shifting will sound more or less realistic for your use case. A good value to start with is something like 5 or 10.

##### Synth&lowbar;SHELVE&lowbar;CUTOFF

Filters out all frequencies over the cutoff frequency.

##### Synth&lowbar;BRICKWALL&lowbar;LIMITER

This modules clips a signal to make it fit into the range of [-1;1]. It doesn't do anything to prevent the distortion that happens when clipping loud signals. You can use this as effect (for instance to create a slightly clipped sine wave). However, it's probably a good idea to run the signal through a lowpass filter afterwards if you do so, to make it sound less agressive.

##### Synth&lowbar;STD&lowbar;EQUALIZER

This is a nice parametric equalizer building block. It's parameters are

invalue, outvalue

  The signal that gets filtered by the equalizer.

low

  How low frequencies should be changed. The value is in dB, while 0 means don't change low frequencies, -6 would mean take them out by 6dB, and +6 mean boost them by 6dB.

mid

  How middle frequencies should be changed by the equalizer in dB (see low).

high

  How high frequencies should be changed by the equalizer in dB (see low).

frequency

  This is the center frequency of the equalizer in Hz, the mid frequencies are around that spectrum, the low and high frequencies below and above. Note that the frequency may not be higher than half the sampling rate, usually that is 22050 Hz, and not lower than 1 Hz.

q

  This influences how broad the mid spectrum is. It must be be a positive number > 0. A value of one is reasonable, higher values of q mean a narrower spectrum of middle frequencies. Lower values than one mean a broader sprectrum.

##### Synth&lowbar;RC

A damped resonator filter filtering all frequencies around some peak value. There is no useful way of specifying middle frequency (that won't be cut), since the input are two strange constants f and b. The code is very old, from the first days of the synthesizer, and will probably replaced by a new filter which will have a frequency and a resonance value as parameters.

Try something like b=5, f=5 or b=10, f=10 or b=15, f=15 though.

##### Synth&lowbar;MOOG&lowbar;VCF

Filters out all frequencies over the cutoff frequency (it's a 24db 4pole filter, which filters -24db per octave above the cutoff frequency), but offers an additional parameter for tuning the filter resonance, while 0 means no resonance and 4 means self oscillation.

#### Midi + Sequencing

##### Synth&lowbar;MIDI&lowbar;TEST

This modules loads an instrument structure from a file, and registers itself as midi output with the aRts midi manager. Notes sent to this output will result in instrument voices being created. Note: you can setup something like this more convenient in artscontrol than manually in artsbuilder.

##### Synth&lowbar;SEQUENCE

Will play a sequence of notes over and over again. The notes are given in tracker notation, and are seperated by semicolons. An example is `A-3;C-4;E-4;C-4;`. The speed is given as seconds per note, so if you want to get 120 bpm, you will probably specify 0.5 seconds/note, as 60 seconds/0.5 seconds per note=120 bpm.

You can give each note an length relative to the speed by using a colon after the note and then then length. `A-3:2;C-4:0.5;D-4:0.5;E-4;` demonstrates this. As you see, midi composing programs tend to offer more comfort ;)

The Synth&lowbar;SEQUENCE gives additional information about the position of the note it is playing right now, while 0 means just started and 1 means finished. This information you can use with Synth&lowbar;PSCALE (see below).

#### Samples

##### Synth&lowbar;PLAY&lowbar;WAV

This will play a wav file. It will only be present if you have libaudiofile on your computer. The wave file will start as soon as the module gets created. It will stop as soon as it's over, then finished will be set to 1. The speed parameter can be used to replay the file faster or slower, where 1.0 is the normal (recorded) speed.

#### Sound IO

##### Synth&lowbar;PLAY

You will normally not need this module, unless you are writing standalone applications. Inside artsd, there normally is already a Synth&lowbar;PLAY module, and creating another one will not work..

The Synth&lowbar;PLAY-module will output your audio signal to the soundcard. The left and right channels should contain the normalized input for the channels. If your input is not between -1 and 1, you get clipping.

As already mentioned, there may only be one Synth&lowbar;PLAY module used, as this one directly accesses your soundcard. Use busses if you want to mix more than one audio stream together before playing. Use the Synth&lowbar;AMAN&lowbar;PLAY module to get something like an output inside artsd.

Note that Synth&lowbar;PLAY also does the timing of the whole structure. This means: no Synth&lowbar;PLAY = no source for timing = no sound. So you absolutely need (exactly) one Synth&lowbar;PLAY object.

##### Synth&lowbar;RECORD

You will normally not need this module, unless you are writing standalone applications. Inside artsd, there normally is already a Synth&lowbar;RECORD module, and creating another one will not work..

The Synth&lowbar;RECORD-module will record a signal from the soundcard. The left and right channels will contain the input for the channels (between -1 and 1).

As already mentioned, there may only be one Synth&lowbar;RECORD module used, as this one directly accesses your soundcard. Use busses if you want to use the recorded audio stream in more than one place. Use the Synth&lowbar;AMAN&lowbar;RECORD module to get something like an input inside artsd. For this to work, artsd must run with full duplex enabled

##### Synth&lowbar;AMAN&lowbar;PLAY

The Synth&lowbar;AMAN&lowbar;PLAY-module will output your audio signal. It is nice (but not necessary) if you output a normalized signal (between -1 and 1).

This module will use the audio manager to assign where the signal will be played. The audio manager can be controlled through artscontrol. To make it more intuitive to use, it is good to give the signal you play a name. This can be achieved through setting title. Another feature of the audio manager is to be able to remember where you played a signal the last time. To do so it needs to be able to distinguish signals. That is why you should assign something unique to autoRestoreID, too.

##### Synth&lowbar;AMAN&lowbar;RECORD

The Synth&lowbar;AMAN&lowbar;RECORD-module will record an audio signal from an external source (i.e. line in/microphone) within artsd. The output will be a normalized signal (between -1 and 1).

This module will use the audio manager to assign where the signal will be played. The audio manager can be controlled through artscontrol. To make it more intuitive to use, it is good to give the signal you record a name. This can be achieved through setting title. Another feature of the audio manager is to be able to remember where you recorded a signal the last time. To do so it needs to be able to distinguish signals. That is why you should assign something unique to autoRestoreID, too.

##### Synth&lowbar;CAPTURE

The Synth&lowbar;CAPTURE-module will write an audio signal to a wave file on your hard disc. The file will always be called /tmp/mcop-usename/capture.wav

#### Tests

##### Synth&lowbar;NIL

This just does nothing. It is only useful for test situations.

##### Synth&lowbar;DEBUG

You can use this for debugging. It will print out the value of the signal at invalue in regular intervals (ca. 1 second), combined with the comment you have specified. That way you can find out if some signals stay in certain ranges, or if they are there at all.

##### Synth&lowbar;MIDI&lowbar;DEBUG

You can use this to debug how your midi events are actually arriving in aRts.

When a MIDI&lowbar;DEBUG is running artsserver will print out a lines like

    201 100753.837585 on 0 42 127

    202 101323.128355 off 0 42

While the first line would be telling you that 100753ms (that is 100 seconds) after the MIDI&lowbar;DEBUG started, a midi on event arrived on channel 0. This midi on event had the velocity (volume) of 127, the loudest possible. The next line shows the midi release event. [ TODO: this does not work currently, make it work, and do it via midi manager ].

##### Synth&lowbar;DATA

This creates a signal with a constant number.

#### Oscillation & Modulation

##### Synth&lowbar;FREQUENCY

All oscillators in aRts don't require a frequency as input, but a position in the wave. The position should be between 0 and 1, which maps for a standard Synth&lowbar;WAVE&lowbar;SIN object to the range 0..2*pi. To generate oscillating values from a frequency, a Synth&lowbar;FREQUENCY modules is used.

##### Synth&lowbar;FM&lowbar;SOURCE

This is used for frequency modulation. Put your frequency to the frequency input and put another signal on the modulator input. Then set modlevel to something, say 0.3. The frequency will be modulated with modulator then. Just try it. Works nice when you put a feedback in there, that means take a combination of the delayed output signal from the Synth&lowbar;FM&lowbar;SOURCE (you need to put it to some oscillator as it only takes the role of Synth&lowbar;FREQUENCY) and some other signal to get good results.

Works nicely in combination with Synth&lowbar;WAVE&lowbar;SIN oscillators.

#### Wave Forms

##### Synth&lowbar;WAVE&lowbar;SIN

Sinus oscillator. Put a pos signal from Synth&lowbar;FREQUENCY or Synth&lowbar;FM&lowbar;SOURCE at the input. And get a sinus wave as output. The pos signal specifies the position in the wave, the range 0..1 is mapped to 0..2*pi internally.

##### Synth&lowbar;WAVE&lowbar;TRI

Triangle oscillator. Put a pos signal from Synth&lowbar;FREQUENCY or Synth&lowbar;FM&lowbar;SOURCE at the input. And get a triangle wave as output. The pos signal specifies the position in the wave, the range 0..1 is mapped to 0..2*pi internally. Be careful. The input signal *MUST* be in the range 0..1 for the output signal to produce good results.

##### Synth&lowbar;NOISE

Noise generator. This generates a random signal between -1 and 1.

##### Synth&lowbar;WAVE&lowbar;SQUARE

Square oscillator. Put a pos signal from Synth&lowbar;FREQUENCY or Synth&lowbar;FM&lowbar;SOURCE at the input. And get a square wave as output. The pos signal specifies the position in the wave, the range 0..1 is mapped to 0..2*pi internally. Be careful. The input signal *MUST* be in the range 0..1 for the output signal to produce good results.

##### Synth&lowbar;WAVE&lowbar;SOFTSAW

Softened saw wave, similar in look like the Synth_WAVE_TRI oscillator. Put a pos signal from Synth&lowbar;FREQUENCY or Synth&lowbar;FM&lowbar;SOURCE at the input. You'll get a softened saw wave as output. The pos signal specifies the position in the wave, the range 0..1 is mapped to 0..2*pi internally. Be careful. The input signal *MUST* be in the range 0..1 for the output signal to produce good results.

##### Synth&lowbar;WAVE&lowbar;PULSE

Pulse oscillator - this module is similar in spirit like the rectangular oscillator (Synth_WAVE_RECT), but it provides a configurable up/down ratio, through the dutycycle parameter. Put a pos signal from Synth&lowbar;FREQUENCY or Synth&lowbar;FM&lowbar;SOURCE at the input. Get a pulse wave as output. The pos signal specifies the position in the wave, the range 0..1 is mapped to 0..2*pi internally. Be careful. The input signal *MUST* be in the range 0..1 for the output signal to produce good results.

### Visual Modules Reference

TODO when visual modules are more "finished".

## Porting Applications to &arts;

### Using artsdsp

### Adding Native &arts; support

## Contributing to &arts;

### How You Can Help

The &arts; project can use help from developers to make existing multimedia applications &arts;-aware, write new multimedia applications, and enhance the capabilities of &arts;. However, you don't have to be a developer to contribute. We can also use help from testers to submit bug reports, translators to translate the application text and documentation into other languages, artists to design bitmaps (especially for artsbuilder modules), musicians to create sample &arts; modules, and writers to write or proofread documentation.

### Mailing Lists

### Coding Standards

For getting a consistent reading through all the sources, it is important to keep the coding style the same, all over the aRts source. Please, even if you just write a module, try to write/format your source accordingly, as it will make it easier for different people to maintain the source tree, and easier to copy pieces of from one source to another.

Naming of member functions

  QT/Java style, that means capitalization on word breaks, and first letter always without capitalization; no underscores.

  This means for instance

         createStructureDesc()
         updateWidget();
         start();

Class members

  Class members are not capitalized, such as menubar or button.

  When there are accessing functions, the standard should be the MCOP way, that is, when having an long member foo, which shouldn't be visible directly, you create

         foo(long new_value);
         long foo();

  functions to get and set the value. In that case, the real value of foo should be stored in &lowbar;foo.

Class names

  All classes should be wordwise capitalized, that means ModuleView, SynthModule. All classes that belong to the libraries should use the Arts namespace, like Arts::Soundserver.

  The implementations of MCOP classes should get called Class&lowbar;impl, such as SoundServer&lowbar;impl.

Parameters

  Parameters are always uncapitalized.

Local variables

  Local variables are always uncapitalized, and may have names like i, p, x, etc. where appropriate.

Tab width (Shift width)

  One tab is as long as 4 spaces.

Naming of source files

  Source files should have no capitalization in the name. They should have the name of the class when they implement a single class. Their extension is .cc if they refer to Qt/GUI independant code, and .cpp if they refer to Qt/GUI dependant code. Implementation files for interfaces should be called foo_impl, if Foo was the name of the interface.

  IDL files should be called in a descriptive way for the collection of interfaces they contain, also all lower case. Especially it is not good to call an idl file like the class itself, as the .mcopclass trader and type info entries will collide, then.

## Future Work

## References

&arts; project web site

&kde; Multimedia web site

Chapter 14 (Multimedia) Of &kde; 2.0 Development book, available for purchase or viewable on-line at http://www.andamooka.org

## Questions and answers

This section answers some frequently asked questions about &arts;.

### General Questions

Does &kde; support my sound card for audio output?

&kde; uses &arts; to play sound, and &arts; uses the &Linux; kernel sound drivers, either OSS or ALSA (using OSS emulation). If your sound card is supported by either ALSA or OSS and properly configured (&ie; any other &Linux; application can output sound), it will work.

Is there sound support on platforms other than &Linux;?

There is currently only support for OSS (or compatible) drivers on other platforms (&eg; FreeBSD). You are welcome to contribute by adding support for other platforms. The relevant source code is `kdelibs/arts/flow/audiosubsys.cc`.

I can't play `wav` files with artsd!

Check that artsd is linked to `libaudiofile` (``ldd` `artsd``). If it isn't, download kdesupport, recompile everything, and it will work.

I hear sound when logged in as <systemitem <!-- DocBook 4.1: class="username" --> >root but no other users have sound!

The permissions of the file <filename <!-- DocBook 4.1: class="devicefile" --> >/dev/dsp affect which users will have sound. To allow everyone to use it, do this:

1. log in as <systemitem <!-- DocBook 4.1: class="username" --> >root

2. open a &konqueror; window

3. go into the `/dev` directory

4. click on the file `dsp` with the right mouse button, and choose properties.

5. click on the Permissions tab

6. check the Read and Write check boxes in all sections

7. click on ok

You can achieve the same effect in a terminal window using the command ``chmod` `666 /dev/dsp``.

For restricting access to sound to specific users, you can use group permissions. On some &Linux; distributions, for instance Debian/Potato, `/dev/dsp` is already owned by a group called <systemitem <!-- DocBook 4.1: class="groupname" --> >audio, so all you need to do is add the users to this group.

This helps for artsd, but what about &kmix;, &kmid;, &kscd;,&etc;?

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 midi0, midi1, ..., then only the 0-version is listed here):

<filename <!-- DocBook 4.1: class="devicefile" --> >/dev/admmidi0 <filename <!-- DocBook 4.1: class="devicefile" --> >/dev/adsp0 <filename <!-- DocBook 4.1: class="devicefile" --> >/dev/amidi0 <filename <!-- DocBook 4.1: class="devicefile" --> >/dev/amixer0 <filename <!-- DocBook 4.1: class="devicefile" --> >/dev/audio <filename <!-- DocBook 4.1: class="devicefile" --> >/dev/audio0 <filename <!-- DocBook 4.1: class="devicefile" --> >/dev/cdrom <filename <!-- DocBook 4.1: class="devicefile" --> >/dev/dmfm0 <filename <!-- DocBook 4.1: class="devicefile" --> >/dev/dmmidi0 <filename <!-- DocBook 4.1: class="devicefile" --> >/dev/dsp <filename <!-- DocBook 4.1: class="devicefile" --> >/dev/dsp0 <filename <!-- DocBook 4.1: class="devicefile" --> >/dev/midi0 <filename <!-- DocBook 4.1: class="devicefile" --> >/dev/midi0 <filename <!-- DocBook 4.1: class="devicefile" --> >/dev/midi00 <filename <!-- DocBook 4.1: class="devicefile" --> >/dev/midi00 <filename <!-- DocBook 4.1: class="devicefile" --> >/dev/mixer <filename <!-- DocBook 4.1: class="devicefile" --> >/dev/mixer0 <filename <!-- DocBook 4.1: class="devicefile" --> >/dev/mpu401data <filename <!-- DocBook 4.1: class="devicefile" --> >/dev/mpu401stat <filename <!-- DocBook 4.1: class="devicefile" --> >/dev/music <filename <!-- DocBook 4.1: class="devicefile" --> >/dev/rmidi0 <filename <!-- DocBook 4.1: class="devicefile" --> >/dev/rtc <filename <!-- DocBook 4.1: class="devicefile" --> >/dev/sequencer <filename <!-- DocBook 4.1: class="devicefile" --> >/dev/smpte0 <filename <!-- DocBook 4.1: class="devicefile" --> >/dev/sndstat

What can I do if artsd doesn't start or crashes while running?

First of all: try using the default settings in KControl (of if you are starting manually, don't give additional options besides maybe -F10 -S4096 for latency). Especially full duplex is likely to break with various drivers, so try disabling it.

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:

    % artsd -F10 -S4096

You can also add the -l0 option, which will print more information about what is happening, like this:

    % artsd -l0 -F10 -S4096

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 "how" it crashes. If you want to report a bug, producing a backtrace with gdb and/or an strace may help finding the problem.

### Non-Arts Applications

As soon as &kde; is running, no other application can access my sound device!

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.

You said it suspends after 60 seconds, it doesn't for me!

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.

How can I run old, non-&arts; applications?

Run them using the artsdsp. For instance, if you normally would run:

    &percnt; mpg123 foo.mp3

instead use:

    &percnt; artsdsp mpg123 foo.mp3

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.

I can't run artsdsp with any application, it always crashes!

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.

Are there theoretical limitations with some applications that will prevent them from ever working with artsdsp ?

No. Using `artsdsp` can result in slightly more latency and CPU usage that using the &arts; APIs 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 every application to work with it (including large applications like Quake 3).

What can I do if an application doesn't work with `artsdsp`?

You can wait for artsd to suspend or use the command ``artsshell` `suspend`` 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.

If the server is busy, a crude but effective way to get rid of it is:

    &percnt; killall artsd ; killall artswrapper
    Now start your own application.
    &percnt; kcminit arts

Any currently running &arts; applications may crash, however, once you kill the server.

What about applications written for KDE1?

If you are running KDE1 applications, which output sound via the KDE1 audio server, you will need to run kaudioserver to make it work. You can start kaudioserver in the same way than other non-aRts-applications:

    &percnt; artsdsp kaudioserver

You will need to have installed kaudioserver (from the same source where you got your KDE1 applications from) - it belongs to KDE1, not KDE2.

What about applications using the enlightened sound daemon, ESD?

The issue is similar than with kaudioserver. Such applications will need a running esd server. You can start esd via artsdsp, and every ESD aware application should work fine, like this:

    &percnt; artsdsp esd

### Latency

I sometimes hear short pauses when listening to music, is this a bug?

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 250ms or don't care), which should improve the situation.

What's the effect of the response time setting?

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 CPU resources, and be more likely to cause dropouts.

Is there anything else I can do to prevent pauses?

For users of IDE drives, you can use the `hdparm` command to put your IDE drive in DMA 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 `hdparm` command for more details. I have successfully used the following command:

    &percnt; hdparm -c1 -d1 -k1 -K1 /dev/hda

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 `/etc/rc.boot`).

Why is artsd taking so much CPU time?

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.

### Network Transparency

What do I need for network transparency?

Enable it in the &kcontrol; Sound Server settings (enable X11 server for security information and network transparency). Then copy your `.mcoprc` 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 `/etc/hosts`).

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:

    &percnt; artsd -n -F 5 -S 8192

The `-n` parameter is for network transparency, while the others configure latency.

Your `.mcoprc` file should have this entry:

    GlobalComm=Arts::X11GlobalComm

on all machines involved, in order for network transparency to work, This is what is enabled by the X11 server for security information control panel setting.

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 hostname.domainname combination. If your domain name is empty, it will try to connect to hostname. (note the extra dot). Adding an entry like this to `/etc/hosts` (&ie; `orion.` if your hostname is orion) works around the problem.

How do I debug network transparency if it doesn't work?

Assuming you have the &kde; source code, go to `kdelibs/arts/examples`, and run ``make` `check`` to compile some programs, including referenceinfo. Then run

    &percnt; ./referenceinfo global:Arts&lowbar;SimpleSoundServer

The output will indicate the host name and port being used by &arts;. For example, `tcp:orion:1698` would mean that any client trying to use network transparency should know how to reach host orion.

### Other Issues

I can't use artsbuilder. It crashes when executing a module!

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 artsbuilder results in the error message [artsd] Synth_PLAY: audio subsystem is already used.

You should use a Synth_AMAN_PLAY instead of a Synth_PLAY module and the problem will go away. Also see the artsbuilder help file (hit F1 in artsbuilder).

Recent versions of artsbuilder (&kde; 2.1 beta 1 and later) come with a set of examples which you can use.

## &arts; Copyright and Licensing

&arts; software copyright 1998-2001 Stefan Westerfeld stefan@space.twc.de

Documentation copyright 1999-2001 Stefan Westerfeld stefan@space.twc.de and Jeff Tranter tranter@kde.org.

&underFDL;

All libraries that are in &arts; are licensed under the terms of the GNU Lesser General Public license. The vast majority of the &arts; code is in the libraries, including the whole of MCOP and ArtsFlow. This allows the libraries to be used for non-free/non-open source applications if desired.

There are a few programs (such as artsd), that are released under the terms of the GNU General Public License. As there have been different opinions on whether or not linking GPL programs with &Qt; is legal, I also added an explicit notice which allows that, in addition to the GPL: permission is also granted to link this program with the &Qt; library, treating &Qt; like a library that normally accompanies the operating system kernel, whether or not that is in fact the case.

## Introduction to Digital Audio

digital sampling, filters, effects, &etc;

## Introduction to MIDI

ALSA

  Advanced &Linux; Sound Architecture; a &Linux; sound card driver; not currently included with the standard kernel source code.

&arts;

  Analog Real-Time Synthesizer; the name of the multimedia architecture/library/toolkit used by the &kde; project (note capitalization)

BSD

  Berkeley Software Distribution; here refers to any of several free &UNIX;-compatible operating systems derived from BSD &UNIX;.

CORBA

  Common Object Request Broker Architecture; a standard for implementing object-oriented remote execution.

CVS

  Concurrent Versions System; a software configuration management system used by many software projects including KDE and &arts;.

FFT

  Fast Fourier Transform; an algorithm for converting data from the time to frequency domain; often used in signal processing.

Full Duplex

  The ability of a sound card to simultaneously record and play audio.

GPL

  GNU General Public License; a software license created by the Free Software Foundation defining the terms for releasing free software.

GUI

  Graphical User Interface

IDL

  Interface Definition Language; a programming language independent format for specifying interfaces (methods and data).

&kde;

  K Desktop Environment; a project to develop a free graphical desktop environment for &UNIX; compatible systems.

LGPL

  GNU Lesser General Public License; a software license created by the Free Software Foundation defining the terms for releasing free software; less restrictive than the GPL and often used for software libraries.

MCOP

  Multimedia COmmunication Protocol; the protocol used for communication between &arts; software modules; similar to CORBA but simpler and optimized for multimedia.

MIDI

  Musical Instrument Digital Interface; a standard protocol for communication between electronic musical instruments; often also used to refer to a file format for storing MIDI commands.

OSS

  Open Sound System; the sound drivers included with the &Linux; kernel (sometimes called OSS/Free) or a commercial version sold by 4Front Technologies.

## Installing &arts;

In order to use &arts; you obviously need to have it installed and running on your system. There are two approaches for doing this, which are described in the next sections.

### Installing a Precompiled Binary Release

The quickest and easiest way to get &arts; up and running is to install precompiled binary packages for your system. Most recent &Linux; distributions include &kde;, and if it is &kde; 2.0 or later it will include &arts;. If &kde; is not included on your installation media it may be available as a download from your operating system vendor. Alternatively it may be available from third parties. Make sure that you use packages that are compatible with your operating system version.

A basic install of &kde; will include the sound server, allowing most applications to play sound. If you want the full set of multimedia tools and applications you will likely need to install additional optional packages.

The disadvantage of using precompiled binaries is that they may not be the most recent version of &arts;. This is particularly likely if they are provided on &CD-ROM;, as the pace of development of &arts; and &kde; is such that &CD-ROM; media cannot usually keep pace. You may also find that, if you have one of the less common architectures or operating system distributions, precompiled binary packages may not be available and you will need to use the second method.

### Building From Source

While time consuming, the most flexible way to build &arts; is to compile it yourself from source code. This ensures you have a version compiled optimally for your system configuration and allows you to build the most recent version.

You have two choices here -- you can either install the most recent stable version included with &kde; or you can get the most recent (but possibly unstable) version directly from the &kde; project CVS repository. Most users who aren't developing for &arts; should use the stable version. You can download it from ftp://ftp.kde.org or one of the many mirror sites. If you are actively developing for &arts; you probably want to use the CVS version.

Note that at the time of writing, the most recent version of &arts; was only provided as part of &kde;. If you want a standalone version of &arts; you will need to manually build and install only the &arts; portions of &kde;.

Note also that if you are building from CVS, some components of &arts; (&ie; the basic core components including the sound server) are found in the CVS module kdelibs, while additional components (&eg; artsbuilder) are included in the. This may change in the future. You may also find a version in the kmusic module; this is the old (pre-&kde; 2.0) version which is now obsolete.

The requirements for building &arts; are essentially the same as for building &kde;. The configure scripts should detect your system configuration and indicate if any required components are missing. Make sure that you have a working sound driver on your system (either the OSS/Free driver in the kernel, OSS driver from 4Front Technologies, or ALSA driver with OSS emulation).

More information on downloading and installing &kde; (including &arts;) can be found in the &kde; &FAQ;.