# The &arts; Handbook

## 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 &arts-builder; 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 or Stefan Westerfeld stefan@space.twc.de 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.

&tools; &artsbuilder-doc; &detail; &arts-midi; &gui; &mcop-ref; &apis; &modules; &porting; &helping; &future; &references; &arts-faq;

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

## 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. If you want to use aRts without KDE, you can download a standalone development snapshot from http://space.twc.de/~stefan/kde/arts-snapshot-doc.html.

Note 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 tdelibs, while additional components (⪚ 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;.

&digitalaudio; &midiintro; &arts-glossary;