You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
358 lines
10 KiB
358 lines
10 KiB
<!-- <?xml version="1.0" ?>
|
|
<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd">
|
|
To validate or process this file as a standalone document, uncomment
|
|
this prolog. Be sure to comment it out again when you are done -->
|
|
|
|
<chapter id="arts-apis">
|
|
<title>&arts; Application Programming Interfaces</title>
|
|
|
|
<sect1 id="api-overview">
|
|
<title>Overview</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
<para>
|
|
There is one important distinction to make: most of the APIs are <emphasis>
|
|
language and location independent</emphasis> because they are specified as
|
|
<emphasis>mcopidl</emphasis>.
|
|
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:
|
|
</para>
|
|
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>core.idl</term>
|
|
<listitem><para>
|
|
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.
|
|
</para></listitem>
|
|
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>artsflow.idl</term>
|
|
|
|
<listitem><para>
|
|
These contain the flow system you will use for connecting audio streams, the
|
|
definition of <emphasis>Arts::SynthModule</emphasis> which is the base for
|
|
any interface that has streams, and finally a few useful audio objects
|
|
</para></listitem>
|
|
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>kmedia2.idl</term>
|
|
|
|
|
|
<listitem><para>
|
|
Here, an object that can play a media, <emphasis>Arts::PlayObject</emphasis>
|
|
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.
|
|
</para></listitem>
|
|
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>soundserver.idl</term>
|
|
|
|
<listitem><para>
|
|
Here, an interface for the system wide sound server artsd is defined. The
|
|
interface is called <emphasis>Arts::SoundServer</emphasis>, 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).
|
|
</para></listitem>
|
|
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>artsbuilder.idl</term>
|
|
<listitem><para>
|
|
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 <emphasis>Arts::StructureDesc</emphasis>,
|
|
<emphasis>Arts::ModuleDesc</emphasis> and <emphasis>Arts::PortDesc</emphasis>
|
|
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.
|
|
</para></listitem>
|
|
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>artsmidi.idl</term>
|
|
|
|
<listitem><para>
|
|
This module defines basic midi functionality, like objects that produce
|
|
midi events, what is a midi event, an <emphasis>Arts::MidiManager</emphasis>
|
|
to connect the producers and consumers of midi events, and so on. As always
|
|
network transparency implied.
|
|
</para></listitem>
|
|
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>artsmodules.idl</term>
|
|
<listitem><para>
|
|
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.
|
|
</para></listitem>
|
|
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>artsgui.idl</term>
|
|
|
|
<listitem><para>
|
|
This cares about visual objects. It defines the basic type <emphasis>
|
|
Arts::Widget</emphasis> 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.
|
|
</para></listitem>
|
|
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
<para>
|
|
Where possible, aRts itself is implemented using IDL. On the other hand, there
|
|
are some <emphasis>language specific</emphasis> 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:
|
|
</para>
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
<term>KNotify, KAudioPlayer (included in libtdecore)</term>
|
|
|
|
<listitem><para>
|
|
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.
|
|
</para></listitem>
|
|
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>libartsc</term>
|
|
<listitem><para>
|
|
Plain C interface for the sound server. Very useful for porting legacy
|
|
applications.
|
|
</para></listitem>
|
|
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>libmcop</term>
|
|
|
|
<listitem><para>
|
|
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.
|
|
</para></listitem>
|
|
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>libartsflow</term>
|
|
<listitem><para>
|
|
Besides the implementation of artsflow.idl, some useful utilities like
|
|
sampling rate conversion.
|
|
</para></listitem>
|
|
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>libqiomanager</term>
|
|
|
|
<listitem><para>
|
|
Integration of MCOP into the Qt event loop, when you write Qt applications
|
|
using MCOP.
|
|
</para></listitem>
|
|
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
|
|
|
|
</sect1>
|
|
<sect1 id="knotify">
|
|
<title>knotify</title>
|
|
<para>
|
|
Not yet written
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="kaudioplayer">
|
|
<title>kaudioplayer</title>
|
|
<para>
|
|
Not yet written
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="libkmid">
|
|
<title>libkmid</title>
|
|
<para>
|
|
Not yet written
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="kmedia2">
|
|
<title>kmedia2</title>
|
|
<para>
|
|
Not yet written
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="soundserver">
|
|
<title>sound server</title>
|
|
<para>
|
|
Not yet written
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="artsflow">
|
|
<title>artsflow</title>
|
|
<para>
|
|
Not yet written
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="capi">
|
|
<title>C <acronym>API</acronym></title>
|
|
|
|
<sect2 id="capiintro">
|
|
<title>Introduction</title>
|
|
|
|
<para> The &arts; C <acronym>API</acronym> 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
|
|
<application>artsd</application>), 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.</para>
|
|
|
|
<para>I did two ports as a proof of concept: <application>mpg123</application>
|
|
and <application>quake</application>. You can get the patches from <ulink
|
|
url="http://space.twc.de/~stefan/kde/download/artsc-patches.tar.gz">here</ulink>.
|
|
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.</para>
|
|
|
|
</sect2>
|
|
|
|
<sect2 id="capiwalkthru">
|
|
<title>Quick Walkthrough</title>
|
|
|
|
<para>Sending audio to the sound server with the <acronym>API</acronym> is very
|
|
simple:</para>
|
|
<procedure>
|
|
<step><para>include the header file using <userinput>#include
|
|
<artsc.h></userinput></para></step>
|
|
<step><para>initialize the <acronym>API</acronym> with
|
|
<function>arts_init()</function></para></step>
|
|
<step><para>create a stream with
|
|
<function>arts_play_stream()</function></para></step>
|
|
<step><para>configure specific parameters with
|
|
<function>arts_stream_set()</function></para></step>
|
|
<step><para>write sampling data to the stream with
|
|
<function>arts_write()</function></para></step>
|
|
<step><para>close the stream with
|
|
<function>arts_close_stream()</function></para></step>
|
|
<step><para>free the <acronym>API</acronym> with
|
|
<function>arts_free()</function></para></step>
|
|
</procedure>
|
|
|
|
<para>Here is a small example program that illustrates this:</para>
|
|
|
|
<programlisting>
|
|
#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;
|
|
}
|
|
</programlisting>
|
|
</sect2>
|
|
|
|
<sect2 id="capiartscconfig">
|
|
<title>Compiling and Linking: <application>artsc-config</application></title>
|
|
|
|
<para>To easily compile and link programs using the &arts; C
|
|
<acronym>API</acronym>, the <application>artsc-config</application> utility is
|
|
provided which knows which libraries you need to link and where the includes
|
|
are. It is called using</para>
|
|
|
|
<screen>
|
|
<userinput><command>artsc-config</command> <option>--libs</option></userinput>
|
|
</screen>
|
|
|
|
<para>to find out the libraries and </para>
|
|
|
|
<screen>
|
|
<userinput><command>artsc-config</command> <option>--cflags</option></userinput>
|
|
</screen>
|
|
|
|
<para>to find out additional C compiler flags. The example above could have been
|
|
|
|
compiled using the command line:</para>
|
|
|
|
<screen>
|
|
<userinput><command>cc</command> <option>-o artsctest artsctest.c `artsc-config --cflags` `artsc-config --libs`</option></userinput>
|
|
|
|
<userinput><command>cc</command> <option>-o artsctest</option> <option>artsctest.c</option> <option>`artsc-config --cflags`</option> <option>`artsc-config --libs`</option></userinput>
|
|
</screen>
|
|
|
|
</sect2>
|
|
|
|
<sect2 id="c-api-reference">
|
|
<title>Library Reference</title>
|
|
|
|
<para>
|
|
[TODO: generate the documentation for artsc.h using kdoc]
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
</sect1>
|
|
</chapter>
|