diff options
Diffstat (limited to 'doc/artsbuilder/index.docbook')
| -rw-r--r-- | doc/artsbuilder/index.docbook | 393 |
1 files changed, 393 insertions, 0 deletions
diff --git a/doc/artsbuilder/index.docbook b/doc/artsbuilder/index.docbook new file mode 100644 index 00000000..ba6649a1 --- /dev/null +++ b/doc/artsbuilder/index.docbook @@ -0,0 +1,393 @@ +<?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 & 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 kdelibs, while additional components (⪚ +<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> +<!-- +Local Variables: +mode: sgml +sgml-omittag:nil +sgml-shorttag:t +sgml-namecase-general:t +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:0 +sgml-indent-data:nil +End: +--> |