  aRts - analog realtime synthesizer
  Stefan Westerfeld (stefan@space.twc.de)
  Version 0.3.4, Sep 29 1999

  This document describes the installation of aRts - the analog realtime
  synthesizer.
  ______________________________________________________________________

  Table of Contents


  1. Introduction

     1.1 What is aRts?
     1.2 Inside aRts

  2. Installation

     2.1 How to obtain aRts
     2.2 Requirements
     2.3 Compilation and installation
     2.4 About root permissions
     2.5 Starting artsbuilder


  ______________________________________________________________________

  1.  Introduction



  1.1.  What is aRts?

  Arts expands to "analog realtime synthesizer", but when you are
  reading this documentation, you perhaps already know...

  This project has been renamed from KSynth to aRts earlier (between
  version 0.2.5 and 0.2.6).

  aRts simulates a complete "modular analog synthesizer" on your -
  digital - computer. Create sounds & music using small modules like
  oscillators for creating waveforms, various filters, modules for
  playing data on your speakers, mixers, faders,... You can build your
  complete setup with the gui of the system, using the modules -
  generators, effects and output - connected to each other.

  Over the time, it has evolved to be useful for a wider range of
  applications than only analog synthesis. Arts is on the way to become
  an audio middleware, which may solve tasks like full duplex effect
  processing, midi synthesis, audio server functionality, emulation of a
  sampler, .... Others like hard disk recording might follow.

  This program is distributed under the GPL (Gnu Public License). Read
  the COPYING-file inside the archive carefully. If you don't agree to
  the GPL, you aren't allowed to use and make changes on the program!


  1.2.  Inside aRts

  While there may be a few software synthesizers already, aRts was
  designed with one goal in mind: flexibility

  So it wasn't designed to be a program where you get two (or ten)
  finished instruments that simply sound nice, and provide some
  parameters. Not even three effects and a mixer.

  Everything - from the smallest building block up to complex structures
  (e.g. mixers with equalizers, effect banks, houndrets of buttons and
  parameters on the screen) - should be able to be buildable of the
  small modules aRts consists of. There shouldn't be something that
  couldn't be recombined, reconfigured, replugged, rerouted or
  redesigned. A virtual studio where everything can be put you want it
  to be.

  Of course there will be instrument libraries, effect libraries, and
  collections of mixers, complex filters, midi processing units, etc.
  that come with aRts. But these are not inside the code, all of it will
  be written in aRts itself, so that everything is accessible via
  aRtsbuilder.  This is still some way to go though - but we're getting
  there.

  Sure enough, new synthesis modules can also easily be written and
  integrated in the aRts system.

  Another issue that leads to flexibility is CORBA:

  The synthesizer basically consists of two parts - a gui where you can
  connect the modules - and a low level synthesizer which can execute
  models. The synthesizer and the gui communicate using CORBA. This
  stategy leads to the possibility that more than one audio application
  share the same room for synthesis. That means, you get - besides the
  midi bus that connects all your applications - some kind of audio
  server where different real time calculations can be done at the same
  time.



  2.  Installation

  2.1.  How to obtain aRts



     binary releases
        Of course the most convenient method of getting aRts installed
        is to use a binary package. Basically, your linux distribution
        should ship with one, and if it doesn't, complain ;). SuSE linux
        for instance does.

        However, there is a solution when you have a distribution that
        doesn't come with aRts, and you desperately want a binary
        package anyway, perhaps because you can't get the sources
        compiled, or the results don't work at all. Starting with aRts
        0.3.3, there will be a static binary available at the aRts
        homepage. The advantage of this is that the static binary should
        run on almost any linux, regardless of the distribution, kernel,
        or libraries. But it is about 8 Megs large, so if you find
        another way of getting aRts installed, use that.

        The following section will however be focused on the classic
        installation from source.



     regular (stable?) source releases
        The best thing is to go to the aRts homepage at
        http://linux.twc.de/arts, and then download it from there (or
        mirrors). Another possibility is to look at
        ftp://ftp.kde.org/pub/kde/unstable/apps/multimedia/sound for a
        recent arts-x.y.z.tgz archive.


     latest development versions
        Arts is developed in the KDE CVS in the module kmusic. So if you
        have access to that, simply use cvs checkout kmusic and you have
        the latest version.

        You can also get snapshots when you don't have CVS access using
        cvsup.  The detailed procedure is documented at
        http://www.kde.org.



  2.2.  Requirements

  Currently it is only tested to compile and run with the following
  software (higher versions are allowed ;) installed on your computer:

  o  Linux 2.0.30 - http://www.linux.org

  o  Qt 1.32 - http://www.troll.no

  o  KDE 1.0 - http://www.kde.org

  o  mico 2.2.3, 2.2.7 or 2.3.0 - http://www.mico.org

     IMPORTANT!! You must compile mico with --disable-mini-stl !!
     Otherwise you can't build aRts

     Mico-2.2.6 has a bug in the idl compiler which leads to incorrect
     reference counting. Arts will work with it, but probably the server
     will not terminate when there is no ArtsBuilder left, and perhaps
     some memoryleak might occur - so if you can avoid it, use a newer
     mico version.


  o  egcs 1.0.2 - http://egcs.cygnus.com

  o  libc6/glibc2 or libc5 with threadsafe X11 libraries (see below)


     Important note for libc5 systems
        (From soundtracker readme, which has the same problem): This
        program makes extensive use of threads. This can be troublesome
        if you are using a libc5 system. You need thread-safe X
        libraries in this case. If ArtsBuilder keeps crashing as soon as
        you start it (with strange X I/O errors), you don't have them.

        You can get a precompiled version from

        http://www.tu-harburg.de/~semk2104/soundtracker/threadedxlibs.tar.bz2

        It's best not to install them over the old X libraries, but to
        put them into a private directory instead and to let the shell
        environment in bash:


          export LD_LIBRARY_PATH=/path/to/threadedxlibs/directory


     in csh/tcsh:


          setenv LD_LIBRARY_PATH /path/to/threadedxlibs/directory


     It also has been reported that compiling against qt-1.42 helped one
     user of a libc5 system who couldn't get aRts running with qt-1.44.
     It would be good if somebody could confirm/debug that.



     Compiling with audiofile 0.1.6
        Libaudiofile ships with a broken header file (with unbalanced
        brackets when __cplusplus is defined), which leads to the error


          error: wav.cc: h:21 parse error before '}'


     when trying to compile the wav-support in src/synthesizer. What you
     can do against that is:

     o  either go to /usr/include/aupvlist.h and remove one of the two
        closing brackets looking like

        ________________________________________________________________
           #ifdef __cplusplus
           }
           #endif
        ________________________________________________________________


     that is on line 59 on my system.

     o  or upgrade libaudiofile to a higer version.

        The broken libaudiofile 0.1.6 for instance ships with Debian 2.1
        or RedHat 6.0, so on this systems expect that problem.



     Problems with calling idl on some systems
        On some systems (like fresh Redhat6 installations), you'll get
        an error message like

        ________________________________________________________________
           /usr/local/bin/idl --query-server-for-narrow synth.idl
           /usr/local/bin/idl: error in loading shared libraries:
              libmico2.2.7.so: cannot open shared object file:
              No such file or directory
        ________________________________________________________________


     To fix that, add /usr/local/lib to /etc/ld.so.conf as root, and run
     ldconfig after that.



     Building without egcs
        I suppose you should be able to use the software if you have
        gcc-2.7.x or gcc-2.8.x as well, but it is possible that you have
        to tune the configure stuff a little. (Report me, if you don't
        get it installed what goes wrong, I should be able to help you).

        If you are using a non-GNU-compiler, you need at least good STL
        support.  When you can build Mico and KDE with it, you should
        probably also be able to build aRts with it.


     Building without linux
        For other operating systems you need to provide another sound
        driver.  Usually it should be possible to take the corresponding
        source from mpeg3play version 0.9.6 (the sound support of the
        synthesizer is based on their routines, see README.sound for
        details) and add realtime capabilities.

        This has only been done for linux so far. Anyway, some people
        reported that aRts also runs under FreeBSD.


     Building without KDE and Qt
        Well, you can build arts without KDE and Qt. Use


          configure --disable-kde


     This will omit building artsbuilder (the visual editor for
     synthesis structures). Arts is not really fun without that though.

     If you really want to do that, I recommend to read the section
     Porting below, and start a new GUI, for instance with

     o  Gtk, Gnome and OrbIt

     o  Java and the mico Java support

     o  whatever else




  2.3.  Compilation and installation

  If you are using a CVS snapshot, start with

  o  make -f Makefile.dist

     Do start the actual compilation (this is for CVS users and users of
     regular releases), use

  o  ./configure

  o  make

  o  make install



  2.4.  About root permissions

  The synthesizer requires realtime priority to work nice. There are
  three possibilities:

     Give the synthesizer wrapper program

        1. Open a terminal windows on your X screen, become root (type
           su and enter your root password).

        2.  Give artsserver.bin the rights:

           _____________________________________________________________
              cd /usr/local/kde/bin
              chown root artswrapper
              chmod u+s artswrapper
           _____________________________________________________________


        This will make it possible that the artsserver takes root rights
        by itself, so you don't need to care about it.

        This wrapper program has been added in aRts-0.3.4 as some people
        had expressed security concerns of having the whole synthesizer
        run as root or suid root. The wrapper program will drop rights
        immediately after setting the scheduler priority to realtime.

        Feedback wether this solution/implementation is really secure is
        greatly appreciated.



     Start the server as root every time
        If you start artsserver manually as root, you will be able to
        use artsbuilder with the appropriate realtime config (you can
        then start artsbuider as user).


     Don't use root permissions
        This is not so nice, because you'll hear that the sound produces
        clicks and breaks as you use the GUI.



  2.5.  Starting artsbuilder

  Now you can start artsbuilder. Under KDE, the application should
  appear under the multimedia section of your K-menu (Arts Builder). If
  it's not there yet, you can try to restart your panel.

  And now, you should be able to play with it.
