tdemultimedia/doc/artsbuilder/index.docbook

<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
 <!ENTITY kappname "&arts;" >
 <!ENTITY tools SYSTEM "tools.docbook">
 <!ENTITY artsbuilder-doc SYSTEM "artsbuilder.docbook"> 
 <!ENTITY detail SYSTEM "detail.docbook">
 <!ENTITY arts-midi SYSTEM "midi.docbook">
 <!ENTITY gui SYSTEM "gui.docbook">
 <!ENTITY mcop-ref SYSTEM "mcop.docbook">
 <!ENTITY arts-mcop SYSTEM "mcop.docbook">
 <!ENTITY apis SYSTEM "apis.docbook">
 <!ENTITY modules SYSTEM "modules.docbook">
 <!ENTITY porting SYSTEM "porting.docbook">
 <!ENTITY helping SYSTEM "helping.docbook">
 <!ENTITY future SYSTEM "future.docbook">
 <!ENTITY references SYSTEM "references.docbook">
 <!ENTITY arts-faq SYSTEM "faq.docbook">
 <!ENTITY arts-glossary SYSTEM "glossary.docbook">
 <!ENTITY digitalaudio SYSTEM "digitalaudio.docbook">
 <!ENTITY midiintro SYSTEM "midiintro.docbook">
 <!ENTITY MCOP "<acronym>MCOP</acronym>">
 <!ENTITY DCOP "<acronym>DCOP</acronym>">
 <!ENTITY MIDI "<acronym>MIDI</acronym>">
 <!ENTITY mcopidl "<application>mcopidl</application>">
 <!ENTITY IDL "<acronym>IDL</acronym>">
 <!ENTITY % English "INCLUDE" > <!-- change language only here -->
 <!ENTITY % addindex "IGNORE">
]>

<book lang="&language;">
<bookinfo>
<title>The &arts; Handbook</title>
<authorgroup>

<author>
<firstname>Stefan</firstname>
<surname>Westerfeld</surname>
<affiliation>
<address><email>stefan@space.twc.de</email></address>
</affiliation>
</author>

<author>
<firstname>Jeff</firstname>
<surname>Tranter</surname>
<affiliation>
<address><email>tranter@kde.org</email></address>
</affiliation>
</author>

<!-- TRANS:ROLES_OF_TRANSLATORS -->
</authorgroup>

<copyright>
<year>1999-2001</year>
<holder>Stefan Westerfeld &amp; Jeff Tranter</holder>
</copyright>
<legalnotice>&FDLNotice;</legalnotice>

<date>2001-06-10</date>
<releaseinfo>1.00.09</releaseinfo>

<abstract><para>This handbook describes &arts;, the Analog Real-time
Synthesizer.</para>

</abstract>

<keywordset>
<keyword>aRts</keyword>
<keyword>artsbuilder</keyword>
<keyword>synthesizer</keyword>
<keyword>multimedia</keyword>
<keyword>structure</keyword>
<keyword>music</keyword>
<keyword>sound</keyword>
<keyword>KDE</keyword>
</keywordset>
</bookinfo>

<chapter id="introduction">
<title>Introduction</title>

<sect1 id="what-is-arts">
<title>What is &arts;?</title>

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

<para>The &artsd; sound server mixes audio from several sources in real
time, allowing multiple sound applications to transparently share access
to sound hardware.</para>

<para>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;.</para>

</sect1>

<sect1 id="using-this-manual">
<title>Using This Manual</title>

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

<para>It is suggested that you first read the <link
linkend="installation">Downloading and Building &arts;</link> 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.</para>

<para>You should then read the sections in the <link
linkend="arts-tools">&arts; Tools</link> chapter, especially &artsd;,
artscontrol;, &artsshell;, and &artsdsp;. This will help you make the
most effective use of &arts;.</para>

<para>If you are interested in going further with &arts;, read the
chapter on <link linkend="artsbuilder">&arts-builder;</link> 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.</para>

<para>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 <link linkend="arts-in-detail">&arts; in
Detail</link>. This should give you an understanding of all of the
concepts that are prerequisites to &arts; software development.</para>

<para>If you are interested specifically in the <acronym>MIDI</acronym>
capabilities of &arts;, you should read the chapter on <link
linkend="midi">&MIDI;</link>.</para>

<!-- TODO
<para>To learn more about the &arts; graphical elements, either as an advanced
user of artsbuilder or to create new elements, read the section on <link
linkend="gui-elements"><acronym>GUI</acronym> Elements</link>.</para>
-->

<para>If you want to develop &arts;-aware multimedia applications, the
<link linkend="arts-apis">&arts; Application Programming
Interfaces</link> chapter covers the different <acronym>API</acronym>s
in detail.</para>

<para>If you want to extend &arts; by creating new modules, read the
<link linkend="arts-modules">&arts; Modules</link> chapter.</para>

<para>If you are modifying an existing application to run under &arts;,
read the chapter on <link linkend="porting">Porting Applications to
&arts;</link>.</para>

<para>You you can find out how to help contribute to the &arts; project
in the <link linkend="contributing">Contributing to &arts;</link>
chapter, read about upcoming &arts; development in the chapter on <link
linkend="future-work">Future Work</link>, and find links to more
information in the <link linkend="references">References</link>
section.</para>

<para>We have also rounded out the manual with some additional material,
including <link linkend="faq">answers to frequently asked
questions</link>, a <link linkend="contributors">list of
contributors</link>, the details on &arts; <link
linkend="copyright-and-licenses">copyright and licensing</link>, and
some background material on <link linkend="intro-digital-audio">digital
audio</link> and <link
linkend="midi-introduction">&MIDI;</link>. A <link
linkend="glossary">glossary</link> of terms is also included.</para>

<note>
<para>
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 <email>tranter@kde.org</email> or Stefan Westerfeld
<email>stefan@space.twc.de</email> first to avoid duplication of effort.
</para>
</note>

</sect1>

<sect1 id="history">
<title>History</title>

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


<para>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
<application>ksynth</application>, the project was renamed &arts; and
the pace of development accelerated. The project at this stage was quite
complete, with a <acronym>CORBA</acronym>-based protocol, dozens of
modules, a graphical module editing tool, C and C++
<acronym>API</acronym>s, 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.</para>

<para>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 <acronym>CORBA</acronym> code with an entirely new
subsystem, &MCOP;, optimized for multimedia. Version 0.4 of &arts; was
included in the &kde; 2.0 release.</para>

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

</sect1>

</chapter>

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

<chapter id="copyright-and-licenses">

<title>&arts; Copyright and Licensing</title>

<para>&arts; software copyright 1998-2001 Stefan Westerfeld
<email>stefan@space.twc.de</email></para>

<para><anchor id="contributors" />
Documentation copyright 1999-2001
Stefan Westerfeld <email>stefan@space.twc.de</email> and
Jeff Tranter <email>tranter@kde.org</email>.
</para>
<!-- TRANS:CREDIT_FOR_TRANSLATORS -->

&underFDL;

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

<para>There are a few programs (such as <application>artsd</application>), that
are released under the terms of the <acronym>GNU</acronym> General Public
License. As there have been different opinions on whether or not linking
<acronym>GPL</acronym> programs with &Qt; is legal, I also added an explicit
notice which allows that, in addition to the <acronym>GPL</acronym>: 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.</para>

</chapter>

<appendix id="installation">
<title>Installing &arts;</title>

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

<sect1 id="binary-install">
<title>Installing a Precompiled Binary Release</title>

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

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

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

</sect1>

<sect1 id="source-install">
<title>Building From Source</title>

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

<para>
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 <acronym>CVS</acronym>
repository. Most users who aren't developing for &arts; should use the stable
version. You can download it from <ulink
url="ftp://ftp.kde.org">ftp://ftp.kde.org</ulink> or one of the many mirror
sites. If you are actively developing for &arts; you probably want to use the
<acronym>CVS</acronym> version. If you want to use aRts without KDE, you can
download a standalone development snapshot from
<ulink url="http://space.twc.de/~stefan/kde/arts-snapshot-doc.html">
http://space.twc.de/~stefan/kde/arts-snapshot-doc.html</ulink>.
</para>

<para>
Note that if you are building from <acronym>CVS</acronym>, some components
of &arts; (&ie; the basic core components including the sound server) are found
in the <acronym>CVS</acronym> module tdelibs, while additional components (&eg;
<application>artsbuilder</application>) 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.
</para>

<para>
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 <acronym>OSS</acronym>/Free
driver in the kernel, <acronym>OSS</acronym> driver from 4Front
Technologies, or 
<acronym>ALSA</acronym> driver with <acronym>OSS</acronym> emulation).
</para>

<para>More information on downloading and installing &kde; (including &arts;)
can be found in the <ulink
url="http://www.kde.org/documentation/faq/index.html">&kde;
&FAQ;</ulink>.</para>

</sect1>

</appendix>

&digitalaudio;
&midiintro;
&arts-glossary;

</book>