Das Handbuch zu aRts

Starten Sie aRts-builder.

Um die Ausgabe zu hören, benötigen Sie ein Synth_AMAN_PLAY-Modul. Sie erstellen ein solches Modul, indem Sie Module->Synthese->SoundIO->Synth_AMAN_PLAY auswählen und auf einen freien Platz im Modulbereich klicken. Platzieren Sie das Modul unterhalb der fünften Linie, da wir noch einige Module oberhalb einfügen werden.

Das Modul hat die Parameter title und autoRestoreID (in der Nähe des linken Kanals) zur Identifikation. Um diese auszufüllen, doppelklicken Sie auf diese Kanäle, wählen Sie konstanter Wert und tippen Sie tutorial in das Eingabefeld. Klicken Sie auf OK zur Bestätigung.

Klicken Sie auf Datei->Struktur ausführen. Sie hören bisher nichts. Das Abspielmodul benötigt irgendetwas als Eingabe. Wenn Sie der Stille eine Weile gelauscht haben, klicken Sie auf OK und gehen Sie zu Schritt 2

Erstellen Sie ein Synth_WAVE_SIN-Modul (im Menü unter Module->Synthese->Wellenformen) und fügen Sie dieses Modul oberhalb von Synth_AMAN_PLAY ein (lassen Sie eine Zeile Platz dazwischen).

Wie Sie sehen, produziert dieses Modul eine Ausgabe, erfordert aber eine Position pos als Eingabe. Verbinden Sie zuerst die Ausgabe mit den Lautsprechern. Klicken Sie auf den Kanal out des Synth_WAVE_SIN-Modules und dann auf den Kanal left des Synth_AMAN_PLAY-Modules. Damit sind diese zwei Module verbunden.

Keiner der Oszillatoren in aRts benötigt eine Frequenz als Eingabe, sondern nur eine Position innerhalb der Welle. Die Position muss zwischen 0 und 1 liegen. Das wird für ein Standard-Synth_WAVE_SIN-Modul auf den Bereich 0 bis 2*Pi umgerechnet. Um eine bestimmte Frequenz zu erzeugen, benötigen Sie ein Synth_FREQUENCY-Modul.

Erstellen Sie ein Synth_FREQUENCY-Modul (unter Module+Synthese+Oszillation & Modulation) und verbinden Sie den „pos“-Ausgang mit dem „pos“-Eingang des Synth_WAVE_SIN-Modules. Legen Sie den Frequenzeingang des Frequenzgenerators auf den konstanten Wert 440.

Wählen Sie Datei->Struktur ausführen. Sie sollten einen Sinuston von 440 Hz in einem von Ihren Lautsprechern hören. Wenn Sie genug zugehört haben, klicken Sie auf OK und gehen Sie zu Schritt 3.

Es würde sich besser anhören, wenn der Sinuston aus beiden Lautsprechern zu hören wäre. Verbinden Sie den rechten Eingang von Synth_PLAY auch mit dem Ausgang von Synth_WAVE_SIN.

Erstellen Sie ein Synth_SEQUENCE-Objekt (durch Module->Synthese->Midi & Sequencing). Es sollte am oberen Rand platziert werden. Wenn Sie mehr Platz benötigen, können Sie die anderen Module verschieben, indem Sie sie auswählen (um mehrere auszuwählen, verwenden Sie Umschalt) und mit der Maus bewegen.

Nun verbinden Sie den Frequenzausgaben von Synth_SEQUENCE mit dem Frequenzeingang des Synth_FREQUENCY-Moduls. Stellen Sie die Geschwindigkeit der Sequenz auf den konstanten Wert 0.13 (der Geschwindigkeitseingang ist der linke).

Geben Sie nun für den rechten Eingang (Sequenz) von Synth_SEQUENCE als konstanten Wert A-3;C-4;E-4;C-4 ein. Das legt eine Sequenz fest. Mehr dazu finden Sie im Abschnitt Modulreferenz.

Wählen Sie Datei->Struktur ausführen. Sie sollten nun eine nette Sequenz hören. Klicken Sie auf OK und gehen Sie zu Schritt 4.

Erstellen Sie ein Synth_PSCALE-Modul (durch Module->Synthese->Hüllkurven). Trennen Sie den Ausgang der SIN-Welle durch doppelklicken und auswählen von nicht verbunden. Verbinden Sie

Setzen Sie schließlich den Eingang top von PSCALE auf einen konstanten Wert, z.B. 0.1.

Das funktioniert folgendermaßen: Das Modul Synth_SEQUENCE gibt zusätzliche Informationen über die Position der gerade erklingenden Note, wobei 0 gerade gestartet und 1 beendet bedeutet. Das Modul Synth_PSCALE skaliert die Lautstärke des Audiostroms von 0 (Ruhe) über 1 (Originallautstärke) zurück zu 0 (Ruhe) abhängig von der Position. Die Position, an der die Maximallautstärke erklingen soll, kann als Positionswert (pos) angegeben werden. 0.1 bedeutet, das nach 10% der Note die Lautstärke ihren Maximalwert erreicht und danach der Ausklingvorgang startet.

Wählen Sie Datei->Struktur ausführen. Sie sollten nun eine nette Sequenz hören. Klicken Sie auf OK und gehen Sie zu Schritt 4.

Starten Sie aRts-builder ein zweites Mal

Erstellen Sie ein Synth_AMAN_PLAY-Modul und benennen Sie es sinnvoll. Erstellen Sie ein Synth_BUS_DOWNLINK-Modul und:

Wenn Sie die Struktur jetzt ausführen, hören Sie noch nichts.

Gehen Sie zurück zur ersten Struktur in der ersten Instanz von aRts-builder mit dem Synth_WAVE_SIN-Modul und ersetzen Sie das Modul Synth_AMAN_PLAY durch ein Synth_BUS_UPLINK,-Modul und benennen Sie es Audio (oder den Namen, den Sie für die entsprechende Komponente in der zweiten Instanz von aRts-builder verwendet haben). Um ein Modul zu löschen, wählen Sie es aus und wählen Sie Bearbeiten->Löschen aus dem Menü ( oder drücken Sie die Entfernen-Taste).

Wählen Sie Datei+Struktur ausführen. Sie hören die Notensequenz wiedergegeben über die Bus-Verbindung.

Wenn Sie herausfinden wollen, wozu eine solche Funktion nützlich ist, klicken Sie auf OK ( in der Instanz, die das Synth_SEQUENCE-Modul enthält, die andere Struktur wird nicht verändert) und gehen Sie zu Schritt 6.

Wählen Sie Datei->Struktur umbenennen in der Instanz, die das Synth_SEQUENCE-Modul enthält und benennen Sie die Struktur Anleitung. Bestätigen Sie mit OK.

Wählen Sie Datei->Speichern

Starten Sie eine weitere Instanz von aRts-builder und wählen Sie Datei->Öffnen und laden Sie die Struktur Anleitung.

Nun wählen Sie im Menü Datei->Struktur ausführen in beiden Instanzen. Sie hören nun die gleiche Struktur zweimal. Abhängig von der Zeitverschiebung wird es mehr oder weniger glücklich klingen.

An dieser Stelle können Sie noch folgendes tun: Starten Sie Noatun und spielen Sie einige mp3-Dateien ab. Starten Sie artscontrol und wählen Sie Ansicht->Audiomanager anzeigen. Es wird Noatun und ihre Struktur „Anleitung“ angezeigt. Klicken Sie doppelt auf Noatun. Daraufhin wird eine Liste der Ausgabegeräte angezeigt. Auch die Struktur wird mit aufgeführt. Sie können die Ausgabe von Noatun über den Audio-Bus durch ihre Wiedergabestruktur leiten.

Jetzt wollen wir den Sinusgenerator in ein wirkliches Musikinstrument verwandeln. Dazu benötigen Sie ein Gerät, das MIDI-Ereignisse an aRts senden kann. Sie können ein externes Keyboard (wie im folgenden beschrieben wird) aber auch einen Sequenzer, der den Midi-bus unterstützt, wie Brahms verwenden.

Beenden Sie zuerst alle überflüssigen Instanzen von aRts-builder. Sie benötigen lediglich die Instanz mit dem Sinusgenerator. Wählen Sie dreimal Kanäle->Audio-Eingangssignal erstellen und dreimal Kanäle->Audio-Ausgangssignal erstellen und platzieren Sie die Module geeignet.

Wählen Sie Kanäle+Positionen/Namen ändern und benennen Sie die Kanäle um in frequency(Frequenz), velocity(Lautstärke), pressed(gedrückt), left(links), right(rechts) und done(stopp) um.

Sie können nun das Modul Synth_SEQUENCE löschen und stattdessen den Frequenzeingangskanal mit dem Modul Synth_FREQUENCY-Eingang verbinden. Was soll nun mit dem pos-Eingang passieren?

Dieser Eingang bleibt unbesetzt, da es keinen Algorithmus der Welt gibt, der vorausberechnen kann, wann ein Spieler die Taste des Keyboards, die er gerade gedrückt hat, wieder loslassen wird. Daher haben wir nur einen Parameter gedrückt stattdessen, der anzeigt, ob der Spieler die Taste noch gedrückt hält (gedrückt=1: Taste immer noch heruntergehalten; gedrückt=0: Taste losgelassen)

Das Synth_PSCALE-Objekt muss nun auch ersetzt werden. Ersetzen Sie es durch ein Synth_ENVELOPE_ADSR-Modul (durch Module->Synthese->Hüllkurven). Verbinden Sie:

Setzen Sie die Parameter attack auf 0.1, decay auf 0.2, sustain auf 0.7 und release auf 0.1.

Weiterhin müssen wir daran denken, das die Instrumentenstruktur wissen muss, wenn der Spieler mit spielen fertig ist, da sonst der letzte Klang nicht beendet wird, auch wenn die letzte Taste losgelassen worden ist. Glücklicherweise weiß die ADSR-Hüllkurve (envelope), wann nichs mehr zu hören ist, da das Signal nach dem Loslassen der letzten Taste irgendwann auf Null reduziert wird.

Das wird erreicht, indem der Ausgang done auf 1 gesetzt wird. Verbinden Sie diesen Ausgang mit dem Ausgangskanal stopp. Damit wird die Struktur beendet, sobald dieser Ausgang auf 1 wechselt.

Benennen Sie die Struktur in Instrument_Anleitung um (durch Datei->Struktur umbenennen). Speichern Sie die Struktur nun (der vorgegebene Name sollte jetzt Instrument_Anleitung sein).

Starten Sie nun artscontrol, wählen Sie Ansicht->Midi-Manager und wählen SieHinzufügen->aRts-Synthese Midi-Ausgabe. Hier sollten Sie in der Lage sein, ihr Instrument (Anleitung) auszuwählen.

Wenn Sie jetzt ein Terminal öffnen und midisend eintippen, sollte midisend und das Instrument im aRts MIDI-Manager angezeigt werden. Wählen Sie beides aus und klicken Sie auf Verbinden. Damit sind die Vorbereitungen abgeschlossen. Nehmen Sie nun ihr Keyboard und beginnen Sie zu spielen (selbstverständlich nachdem Sie es mit dem Computer verbunden haben).

Sie sind nun in der Lage, aRts zu verwenden. Hier sind noch einige Tipps, die den Umgang mit Strukturen verbessern können:

Wenn Sie eine besondere Struktur konstruiert haben, schicken Sie sie an die aRts-Internetseite. Sie kann dann der nächsten Version beigelegt werden.

Angenommen Sie haben ein Programm mit Namen „Mausklick“, das ein „Klicken“ von sich geben soll, wenn Sie eine Maustaste betätigen. Die Verzögerungszeit ist die Zeit zwischen dem Betätigen der Maustaste und dem Ertönen des Klicken. Die Einstellung der Verzögerungszeit besteht aus mehreren Verzögerungszeiten, die unterschiedliche Ursachen haben.

In dieser einfachen Anwendung werden an folgenden Stellen Verzögerungen verursacht:

Die ersten drei Verzögerungszeiten sind extern für aRts. Sie sind wichtig, aber nicht Gegenstand dieser Dokumentation. Sie sollten sich dennoch dieser Verzögerungen bewusst sein, denn selbst wenn Sie alle anderen Verzögerungen sehr gering halten, erhalten Sie vielleicht dennoch nicht exakt die erwarteten Resultate.

Ein Spielbefehl an den Server besteht normalerweise aus einem MCOP-Funktionsaufruf. Es gibt Geschwindigkeitstests,die belegen, dass ein solcher Befehl auf einem Rechner bei der jetzigen Implementation etwa 9000 mal pro Sekunde ausgeführt werden kann. Ich denke, das meiste der Zeit wird Kernel-Overhead für die Umschaltung zwischen verschiedenen Anwendungen sein. Natürlich hängen diese Werte von den exakten Parametertypen des Aufrufs ab. Die Übergabe eines vollständigen Bildes in einem Aufruf dauert länger als die Übergabe eines einzigen Werte. Das Gleiche gilt für den Rückgabewert. Für normale Zeichenketten (wie der Dateiname der zu spielenden wav-Datei) sollte das aber kein Problem darstellen.

Das bedeutet, diese Zeit kann mit 1/9000 Sekunde abgeschätzt werden. Das ist weniger als 0,15 ms. Sie werden sehen, das diese Zeitspanne unwichtig ist.

Die nächste Verzögerungszeit ist die Zeit vom Starten des Soundservers und der Ankunft dieses Beginns auf der Soundkarte. Der Server muss einen Puffer verwenden, damit man keine Aussetzer hört, wenn eine andere Anwendung wie der X11-Server oder das „Mausklick“-Programm aktiv sind. Das wird unter Linux® verwirklicht, indem eine Anzahl Bruchstücke einer bestimmte Größe erzeugt werden. Der Server füllt die Bruchstücke und die Soundkarte spielt die Bruchstücke ab.

Angenommen es gibt drei Bruchstücke. Der Server füllt das Erste, die Soundkarte beginnt mit dem Abspielen. Der Server füllt das Zweite. Der Server füllt das Dritte. Der Server ist fertig, andere Anwendungen können nun aktiviert werden.

Nach dem ersten Bruchstück spielt die Soundkarte das Zweite ab und der Server füllt das erste Bruchstück wieder. Das geht immer so weiter.

Damit ergibt sich eine maximale Verzögerungszeit von (Anzahl der Bruchstücke)*(Größe eines Bruchstückes)/(Samplingrate * (Größe eines Samples)). Bei 44kHz Stereo und 7 Bruchstücken von je 1024 Byte Größe (die aktuellen Standardwerte von aRts) entspricht das einer Verzögerungszeit von 40 ms.

Diese Werte können Sie Ihren Anforderungen anpassen. Allerdings steigt die CPU-Belastung mit kleineren Verzögerungszeiten, da der Soundserver die Puffer häufiger und in kleineren Bruchstücken füllen muss. Es ist außerdem meistens unmöglich, bessere Werte zu erreichen, ohne das Aussetzer zu hören sind, es sei denn, sie versehen den Soundserver mit Echtzeit-Priorität.

Dennoch ist eine Einstellung von 3 Bruchstücken mit je 256 Bytes, die einer Verzögerung von 4,4 ms entsprechen, realistisch. Mit 4,4 ms Verzögerungszeit belastet aRts die CPU im Ruhezustand mit 7,5%. Mit einer Verzögerung von 40 ms beträgt die Belastung etwa 3% (bei einem PII-350, diese Werte können abhängig von der Soundkarte, Kernel-Version und anderen Faktoren variieren).

Jetzt zu der Zeit, die der Klick-Ton von den Lautsprechern bis zum Ohr benötigt. Bei einer angenommenen Distanz von 2 Metern ergibt sich bei einer Schallgeschwindigkeit von 330 Meter pro Sekunde eine Verzögerung von etwa 6 ms.

Streaming-Anwendungen produzieren ihre Klänge selbst. Angenommen, ein Spiel, das einen konstanten Strom von Samples erzeugt, soll nun für die Wiedergabe durch aRts verwendet werden. Als Beispiel: Wenn ich eine Taste drücke, hüpft die Spielfigur und es ertönt ein Boing-Klang.

Als Erstes muss man wissen, wie aRts Streaming realisiert. Der Ablauf ist ähnlich wie bei der Ausgabe auf einer Soundkarte. Das Spiel sendet einige Pakete mit Samples zum Soundserver. Angenommen, es sinc drei Pakete. Sobald der Soundserver das erste Paket wiedergegeben hat, schickt er eine Bestätigung zurück zum Spiel.

Das Spiel erzeugt ein neues Paket und schickt es zum Server. Währenddessen verarbeitet der Server das zweite Paket und so weiter. Die Verzögerungszeiten hier sind ähnlich wie bei dem einfachen Beispiel:

Die externen Verzögerungen sind gehen wiederum über den Inhalt dieses Dokumentes hinaus.

Offensichtlich hängt die Streaming-Verzögerung von der Zeit ab, die alle Pakete benötigen, einmal wiedergegeben zu werden. Also ist diese Zeit (Anzahl der Pakete)*(Größe eines Paketes)/(Samplingrate * (Größe eines Samples))

Wie man sieht, ist das die gleiche Formel, wie sie bei den Bruchstücken verwandt wird. Für Spiele sind solch geringer Verzögerungszeiten wie oben überflüssig. Eine realistische Festlegung für Spiekle wären 2046 Bytes pro Paket bei drei Paketen. Die resultierende Verzögerung ist dann etwa 35 ms.

Diese Berechnung basiert auf folgenden Annahmen: das Spiel rendert 25 Bilder pro Sekunde (für die Anzeige). Einen Verschiebung zwischen Ton und Film von einem Bild nimmt man nicht wahr. Daher ist eine Verzögerung von 1/25 Sekunde für Streaming akzeptabel, was wiederum bedeutet, das 40ms in Ordnung sind.

Außerdem werden die meisten Leute ihre Spiele nicht mit Echtzeit-Priorität spielen und daher ist die Gefahr von Aussetzern nicht zu vernachlässigen. Bei 3 Paketen je 256 Bytes ist Streaming möglich (nach eigenen Tests) - es verbraucht aber eine Menge CPU-Zeit.

Für die Serververzögerungszeiten können Sie genau wie oben rechnen.

Es gibt eine Menge Faktoren, die in komplexen Situationen mit einigen Streaming-Anwendungen und einigen Anderen sowie einigen Plugins auf dem Server einen Einfluß auf die CPU-Zeit haben. Um einige zu nennen:

Für die CPU-Berechnungszeit bei zwei gleichzeitig abgespielten Datenströmen muss man Additionen durchführen. Falls man einen Filter verwendet, sind einige weitere Berechnungen notwendig. Ein einfaches Beispiel mit zwei Strömen mit vier CPU-Zyklen pro Addition führen auf einem 350MHz-Prozessor zu 44100*2*4/350000000 = 0,1% CPU-Auslastung.

aRts internes Scheduling: aRts muss bestimmen, welches Plugin wann was berechnet. Das benötigt Zeit. Wenn man Genaueres wissen will, sollte man einen Profiler zu Rate ziehen. Generell lässt sich Folgendes sagen: je weniger Wert man auf Echtzeit legt (also je größer die zu berechnenden Blöcke sind) um so wenig Scheduling Zeit wird benötigt. Bei mehr als 128 Samples in einem Stück (also einer Bruchstückgröße von 512 Bytes) ist der Scheduling-Aufwand wahrscheinlich nicht einmal nennenswert.

Aufwand zur Konvertierung von Ganzzahlen in Kommazahlen: aRts verwendet intern Kommazahlen als Datenformat. Sie sind einfach zu verarbeiten und auf zeitgemäßen Prozessoren kaum langsamer als Ganzzahlen. Wenn aber Programme ihre Daten nicht in Kommazahlen abspielen (wie ein Spiel, das seine Känge über aRts ausgibt), müssen diese Daten konvertiert werden. Das Gleiche gilt für die Ausgabe auf einer Soundkarte. Soundkarten benötigen Ganzzahlen, also muss eine Konvertierung durchgeführt werden.

Die folgenden Zahlen gehören zu einem Celeron, ungefähre ticks pro Sample, mit -O2 +egcs 2.91.66 (berechnet von Eugene Smith (hamster AT null.ru)). Diese Zahlen sind naturgemäß sehr prozessorabhängig.

convert_mono_8_float: 14
convert_stereo_i8_2float: 28
convert_mono_16le_float: 40
interpolate_mono_16le_float: 200
convert_stereo_i16le_2float: 80
convert_mono_float_16le: 80

Das bedeutet 1% CPU-Zeit für die Konvertierung und 5% für die Interpolation auf diesem 350 MHz-Prozessor.

MCOP Protokoll-Aufwand: MCOP verträgt ungefähr 9000 Aufrufe pro Sekunde. Das hat wenige mit MCOP als mit den zwei Kernelgründen zu tun, die weiter unten beschrieben werden. Dennoch gibt das einen Anhaltspunkt für die Berechnung der Kosten von Streaming.

Jedes übertragene Datenpaket erfordert einen MCOP-Aufruf. Natürlich ist das nur ein Richtwert, da große Pakete langsamer als 9000 Pakete/s sind.

Angenommen man verwendet als Paketgröße 1024 Bytes. Für einen Stream mit 44kHz Stereo muss man also 44100*4/1024 = 172 Pakete pro Sekunde übertragen. Weiter angenommen, 9000 Pakete pro Sekunde entspricht einer CPU-Auslastung von 100%, dann erhält man (172*100)/9000 = 2% CPU-Auslastung bei einem Streaming mit 1024 Bytes pro Paket.

Das sind nur Näherungen. Sie zeigen aber deutlich, dass man viel besser dran ist (wenn man die Verzögerungszeit tolerieren kann) mit einer Paketgröße von 4096 Bytes. Wir können eine kompakte Rechnung durchführen, wenn wir die Paketgröße für 100% CPU-Auslastung berechnen mit 44100*4/9000 = 19,6 Samples; daraus erhalten wir folgende Formel:

Streaming CPU-Auslastung in Prozent = 1960/(Paketgröße)

das ergibt 0,5% CPU-Auslastung bei Streaming mit einer Paketgröße von 4096 Bytes.

Kernel Prozeß-/Kontextumschaltung: dieser Aufwand ist ein Teil des MCOP-Protokolls. Die Umschaltung zwischen zwei Prozessen benötigt Zeit. Es wird der Speicher neu aufgeteilt, der Cache wird ungültig, und vieles mehr (falls ein Kernel-Experte dieses liest - teilen Sie mir bitte die genauen Gründe mit). Das bedeutet: es benötigt Zeit.

Ich weiß nicht wie viele Kontextwechsel Linux verträgt, aber sicher nur eine endliche Zahl. Daher nehme ich an, das ein erheblicher Teil des MCOP Protokollaufwandes durch Kontextumschaltung zu Stande kommt. Ich führte einige Tests mit MCOP-Kommunikation innerhalb eines Prozesses durch. Sie war wesentlich schneller (etwa viermal so schnell).

Kernel: Kommunikationsaufwand: Das ist ebenfalls ein Bestandteil des MCOP Protokollaufwandes. Die Datenübertragung zwischen Prozessen wird momentan mittels Sockets durchgeführt. Das ist praktisch, da die üblichen select()-Methoden verwendet werden können, um die Ankunft einer Nachricht zu überprüfen. Das kann leicht mit anderen Ein-/Ausgabequellen wie Audio Ein-/Ausgabe, X11-Server-Kommunikation und einigem Anderen kombiniert werden.

Diese Lese- und Schreibaufrufe kosten mit Sicherheit Prozessorzeit. Kleine Aufrufe (um ein Midi-Ereignis zu übertragen) sind vermutlich nicht so schlimm, große Aufrufe (z.B. um ein Videobild mit einigen Megabytes zu übertragen) stellen sicherlich ein Problem dar.

In MCOP sollte daher möglichst gemeinsam genutzter Speicher verwendet werden. Das sollte aber keine Änderungen für die Anwendungsprogrammierer mit sich bringen.

Durch einen Profiler kann man herausbekommen, in welchem Maße genau heutiges Audio Streaming unter der Nichtverwendung von gemeinsam genutztem Speicher leidet. Da Audio Streaming mit artsd und artscat mit 6% CPU-Auslastung (Wiedergabe von mp3) durchgeführt werden kann (und 5% für den mp3-Dekoder), kann es nicht so schlimm sein. Das enthält alles einschließlich der notwendigen Berechnungen und dem Socket-Aufwand, daher vermute ich, durch gemeinsam genutzten Speicher könnten vielleicht 1% CPU-Auslastung gespart werden.

Diese Zahlen wurden mit der aktuellen CVS-Version ermittelt. Außerdem wollte ich Grenzfälle testen, also sind das Fälle, die in normalen Anwendungen nicht auftreten sollten.

Ich habe ein Programm namens streamsound geschrieben, das Streaming Daten an aRts sendet. Die Anwendung läuft hier mit Echtzeit-Priorität (ohne Probleme) und einem kleinen Plugin (für Lauststärkeskalierung und Clipping) auf seiten des Servers:

 4974 stefan    20   0  2360 2360  1784 S       0 17.7  1.8   0:21 artsd
 5016 stefan    20   0  2208 2208  1684 S       0  7.2  1.7   0:02 streamsound
 5002 stefan    20   0  2208 2208  1684 S       0  6.8  1.7   0:07 streamsound
 4997 stefan    20   0  2208 2208  1684 S       0  6.6  1.7   0:07 streamsound

Das Streaming wird jeweils mit 3 Bruchstücken je 1024 Bytes (18 ms) durchgeführt. Drei Programme laufen gleichzeitig. Das scheint ein bisschen zu viel zu sein; mit einem Profiler kann man versuchen, den Aufwand zu verbessern.

Das ist ein nicht realistisches Testbeispiel. Als weiteren Test wurde versucht, die minimal mögliche Verzögerungszeit herauszufinden. Resultat: man kann Streaming ohne Unterbrechungen mit einem Anwendungsprogramm bei zwei Bruchstücken je 128 Bytes zwischen aRts und der Soundkarte sowie zwischen der Anwendung und aRts durchführen. Das entspricht einer maximalen Verzögerung von 128*4/44100*4 = 3 ms, wobei 1,5 ms von der Soundkarte und 1,5 ms durch die Kommunikation mit aRts entstehen. Beide Anwendungen benötigen Echtzeit-Priorität.

Das benötigt allerdings einen erheblichen Anteil der CPU. Das Beispiel liegt bei etwa 45% auf meinem P-II/350. Es wird ein Klicken hörbar, wenn man Fenster in X11 bewegt oder Festplattenaktivität verursacht. Das hängt mit dem Kernel zusammen. Das Problem ist, das zwei Echtzeitanwendungen einen erheblichen Aufwand verursachen, mehr noch, wenn Sie auch noch miteinander kommunizieren.

Schließlich ein realistischeres Beispiel. Es besteht aus aRts mit artsd und einem artscat (ein Streaming Programm) bei 16 Bruchstücken mit je 4096 Bytes:

 5548 stefan    12   0  2364 2364  1752 R       0  4.9  1.8   0:03 artsd
 5554 stefan     3   0   752  752   572 R       0  0.7  0.5   0:00 top
 5550 stefan     2   0  2280 2280  1696 S       0  0.5  1.7   0:00 artscat

Each namespace declaration corresponds to a „module“ declaration in the MCOP IDL.

// mcop idl

module M {
    interface A
    {
    }
};

interface B;

In this case, the generated C++ code for the IDL snippet would look like this:

// C++ header

namespace M {
    /* declaration of A_base/A_skel/A_stub and similar */
    class A {        // Smartwrapped reference class
        /* [...] */
    };
}

/* declaration of B_base/B_skel/B_stub and similar */
class B {
    /* [...] */
};

So when referring the classes from the above example in your C++ code, you would have to write M::A, but only B. However, you can of course use „using M“ somewhere - like with any namespace in C++.

There is one global namespace called „Arts“, which all programs and libraries that belong to aRts itself use to put their declarations in. This means, that when writing C++ code that depends on aRts, you normally have to prefix every class you use with Arts::, like this:

int main(int argc, char **argv)
{
    Arts::Dispatcher dispatcher;
    Arts::SimpleSoundServer server(Arts::Reference("global:Arts_SimpleSoundServer"));

    server.play("/var/foo/somefile.wav");

The other alternative is to write a using once, like this:

using namespace Arts;

int main(int argc, char **argv)
{
    Dispatcher dispatcher;
    SimpleSoundServer server(Reference("global:Arts_SimpleSoundServer"));

    server.play("/var/foo/somefile.wav");
    [...]

In IDL files, you don't exactly have a choice. If you are writing code that belongs to aRts itself, you'll have to put it into module aRts.

// IDL File for aRts code:
#include <artsflow.idl>
module Arts {        // put it into the Arts namespace
    interface Synth_TWEAK : SynthModule
    {
        in audio stream invalue;
        out audio stream outvalue;
        attribute float tweakFactor;
    };
};

If you write code that doesn't belong to aRts itself, you should not put it into the „Arts“ namespace. However, you can make an own namespace if you like. In any case, you'll have to prefix classes you use from aRts.

// IDL File for code which doesn't belong to aRts:
#include <artsflow.idl>

// either write without module declaration, then the generated classes will
// not use a namespace:
interface Synth_TWEAK2 : Arts::SynthModule
{
    in audio stream invalue;
    out audio stream outvalue;
    attribute float tweakFactor;
};

// however, you can also choose your own namespace, if you like, so if you
// write an application "PowerRadio", you could for instance do it like this:
module PowerRadio {
    struct Station {
        string name;
        float frequency;
    };

    interface Tuner : Arts::SynthModule {
        attribute Station station;     // no need to prefix Station, same module
        out audio stream left, right;
    };
};

Often, in interfaces, casts, method signatures and similar, MCOP needs to refer to names of types or interfaces. These are represented as string in the common MCOP datastructures, while the namespace is always fully represented in the C++ style. This means the strings would contain „M::A“ and „B“, following the example above.

Note this even applies if inside the IDL text the namespace qualifiers were not given, since the context made clear which namespace the interface A was meant to be used in.

Using threads isn't possible on all platforms. This is why aRts was originally written without using threading at all. For almost all problems, for each threaded solution to the problem, there is a non-threaded solution that does the same.

For instance, instead of putting audio output in a seperate thread, and make it blocking, aRts uses non-blocking audio output, and figures out when to write the next chunk of data using select().

However, aRts (in very recent versions) at least provides support for people who do want to implement their objects using threads. For instance, if you already have code for an mp3 player, and the code expects the mp3 decoder to run in a seperate thread, it's usally the easiest thing to do to keep this design.

The aRts/MCOP implementation is built along sharing state between seperate objects in obvious and non-obvious ways. A small list of shared state includes:

All of the above objects don't expect to be used concurrently (d. h. called from seperate threads at the same time). Generally there are two ways of solving this:

aRts follows the first approach: you will need a lock whenever you talk to any of these objects. The second approach is harder to do. A hack which tries to achieve this is available at http://space.twc.de/~stefan/kde/download/arts-mt.tar.gz, but for the current point in time, a minimalistic approach will probably work better, and cause less problems with existing applications.

You can get/release the lock with the two functions:

Generally, you don't need to acquire the lock (and you shouldn't try to do so), if it is already held. A list of conditions when this is the case is:

There are also some exceptions of functions. which you can only call in the main thread, and for that reason you will never need a lock to call them:

But that is it. For everything else that is somehow related to aRts, you will need to get the lock, and release it again when done. Always. Here is a simple example:

class SuspendTimeThread : Arts::Thread {
public:
    void run() {
        /*
         * you need this lock because:
         *  - constructing a reference needs a lock (as global: will go to
         *    the object manager, which might in turn need the GlobalComm
         *    object to look up where to connect to)
         *  - assigning a smartwrapper needs a lock
         *  - constructing an object from reference needs a lock (because it
         *    might need to connect a server)
         */
        Arts::Dispatcher::lock();
        Arts::SoundServer server = Arts::Reference("global:Arts_SoundServer");
        Arts::Dispatcher::unlock();

        for(;;) {            /*
             * you need a lock here, because
             *  - dereferencing a smartwrapper needs a lock (because it might
             *    do lazy creation)
             *  - doing an MCOP invocation needs a lock
             */
            Arts::Dispatcher::lock();
            long seconds = server.secondsUntilSuspend();
            Arts::Dispatcher::unlock();

            printf("seconds until suspend = %d",seconds);
            sleep(1);
        }
    }
}

The following threading related classes are currently available:

See the links for documentation.

As references can point to remote objects, the servers containing these objects can crash. What happens then?

There are other conditions of failure, such as network disconnection (suppose you remove the cable between your server and client while your application runs). However their effect is the same like a server crash.

Overall, it is of course a consideration of policy how strictly you try to trap communcation errors throughout your application. You might follow the „if the server crashes, we need to debug the server until it never crashes again“ method, which would mean you need not bother about all these problems.

An object, to exist, must be owned by someone. If it isn't, it will cease to exist (more or less) immediately. Internally, ownership is indicated by calling _copy(), which increments an reference count, and given back by calling _release(). As soon as the reference count drops to zero, a delete will be done.

As a variation of the theme, remote usage is indicated by _useRemote(), and dissolved by _releaseRemote(). These functions lead a list which server has invoked them (and thus owns the object). This is used in case this server disconnects (d. h. crash, network failure), to remove the references that are still on the objects. This is done in _disconnectRemote().

Now there is one problem. Consider a return value. Usually, the return value object will not be owned by the calling function any longer. It will however also not be owned by the caller, until the message holding the object is received. So there is a time of „ownershipless“ objects.

Now, when sending an object, one can be reasonable sure that as soon as it is received, it will be owned by somebody again, unless, again, the receiver dies. However this means that special care needs to be taken about object at least while sending, probably also while receiving, so that it doesn't die at once.

The way MCOP does this is by „tagging“ objects that are in process of being copied across the wire. Before such a copy is started, _copyRemote is called. This prevents the object from being freed for a while (5 seconds). Once the receiver calls _useRemote(), the tag is removed again. So all objects that are send over wire are tagged before transfer.

If the receiver receives an object which is on his server, of course he will not _useRemote() it. For this special case, _cancelCopyRemote() exists to remove the tag manually. Other than that, there is also timer based tag removal, if tagging was done, but the receiver didn't really get the object (due to crash, network failure). This is done by the ReferenceClean class.

Streams define multimedia data, one of the most important components of a module. Streams are defined in the following format:

[ async ] in|out [ multi ] type stream name [ , name ] ;

Streams have a defined direction in reference to the module, as indicated by the required qualifiers in or out. The type argument defines the type of data, which can be any of the types described later for attributes (not all are currently supported). Many modules use the stream type audio, which is an alias for float since that is the internal data format used for audio stream. Multiple streams of the same type can defined in the same definition uisng comma separated names.

Streams are by default synchronous, which means they are continuous flows of data at a constant rate, such as PCM audio. The async qualifier specifies an asynchronous stream, which is used for non-continuous data flows. The most common example of an async stream is MIDI messages.

The multi keyword, only valid for input streams, indicates that the interface supports a variable number of inputs. This is useful for implementing devices such as mixers that can accept any number of input streams.

Attributes are data associated with an instance of an interface. They are declared like member variables in C++, and can can use any of the primitive types boolean, byte, long, string, or float. You can also use user-defined struct or enum types as well as variable sized sequences using the syntax sequence<type>. Attributes can optionally be marked readonly.

As in C++, methods can be defined in interfaces. The method parameters are restricted to the same types as attributes. The keyword oneway indicates a method which returns immediately and is executed asynchronously.

Several standard module interfaces are already defined for you in aRts, such as StereoEffect, and SimpleSoundServer.

A simple example of a module taken from aRts is the constant delay module, found in the file kdemultimedia/arts/modules/artsmodules.idl. The interface definition is listed below.

interface Synth_CDELAY : SynthModule {
        attribute float time;
        in audio stream invalue;
        out audio stream outvalue;
};

This modules inherits from SynthModule. That interface, defined in artsflow.idl, defines the standard methods implemented in all music synthesizer modules.

The CDELAY effect delays a stereo audio stream by the time value specified as a floating point parameter. The interface definition has an attribute of type float to store the delay value. It defines two input audio streams and two output audio streams (typical of stereo effects). No methods are required other than those it inherits.

There are various requirements for how a module can do streaming. To illustrate this, consider these examples:

The first case is the simplest: upon receiving 200 samples of input the module produces 200 samples of output. It only produces output when it gets input.

The second case produces different numbers of output samples when given 200 input samples. It depends what conversion is performed, but the number is known in advance.

The third case is even worse. From the outset you cannot even guess how much data 200 input bytes will generate (probably a lot more than 200 bytes, but...).

The last case is a module which becomes active by itself, and sometimes produces data.

In aRtss-0.3.4, only streams of the first type were handled, and most things worked nicely. This is probably what you need most when writing modules that process audio. The problem with the other, more complex types of streaming, is that they are hard to program, and that you don't need the features most of the time. That is why we do this with two different stream types: synchronous and asynchronous.

Synchronous streams have these characteristics:

Asynchronous streams, on the other hand, have this behaviour:

When you declare streams, you use the keyword „async“ to indicate you want to make an asynchronous stream. So, for instance, assume you want to convert an asynchronous stream of bytes into a synchronous stream of samples. Your interface could look like this:

interface ByteStreamToAudio : SynthModule {
    async in byte stream indata;   // the asynchonous input sample stream

    out audio stream left,right;   // the synchronous output sample streams
};

Suppose you decided to write a module to produce sound asynchronously. Its interface could look like this:

interface SomeModule : SynthModule
{
    async out byte stream outdata;
};

How do you send the data? The first method is called „push delivery“. With asynchronous streams you send the data as packets. That means you send individual packets with bytes as in the above example. The actual process is: allocate a packet, fill it, send it.

Here it is in terms of code. First we allocate a packet:

DataPacket<mcopbyte> *packet = outdata.allocPacket(100);

The we fill it:

// cast so that fgets is happy that it has a (char *) pointer
char *data = (char *)packet->contents;

// as you can see, you can shrink the packet size after allocation
// if you like
if(fgets(data,100,stdin))
    packet->size = strlen(data);
else
    packet->size = 0;

Now we send it:

packet->send();

This is quite simple, but if we want to send packets exactly as fast as the receiver can process them, we need another approach, the „pull delivery“ method. You ask to send packets as fast as the receiver is ready to process them. You start with a certain amount of packets you send. As the receiver processes one packet after another, you start refilling them with fresh data, and send them again.

You start that by calling setPull. For example:

outdata.setPull(8, 1024);

This means that you want to send packets over outdata. You want to start sending 8 packets at once, and as the receiver processes some of them, you want to refill them.

Then, you need to implement a method which fills the packets, which could look like this:

void request_outdata(DataPacket<mcopbyte> *packet)
{
    packet->size = 1024;  // shouldn't be more than 1024
    for(int i = 0;i < 1024; i++)
        packet->contents[i] = (mcopbyte)'A';
    packet->send();
}

Thats it. When you don't have any data any more, you can start sending packets with zero size, which will stop the pulling.

Note that it is essential to give the method the exact name request_streamname.

We just discussed sending data. Receiving data is much much simpler. Suppose you have a simple ToLower filter, which simply converts all letters in lowercase:

interface ToLower {
    async in byte stream indata;
    async out byte stream outdata;
};

This is really simple to implement; here is the whole implementation:

class ToLower_impl : public ToLower_skel {
public:
    void process_indata(DataPacket<mcopbyte> *inpacket)
    {
        DataPacket<mcopbyte> *outpacket = outdata.allocPacket(inpacket->size);

        // convert to lowercase letters
        char *instring = (char *)inpacket->contents;
        char *outstring = (char *)outpacket->contents;

        for(int i=0;i<inpacket->size;i++)
            outstring[i] = tolower(instring[i]);

        inpacket->processed();
        outpacket->send();
    }
};

REGISTER_IMPLEMENTATION(ToLower_impl);

Again, it is essential to name the method process_streamname.

As you see, for each arriving packet you get a call for a function (the process_indata call in our case). You need to call the processed() method of a packet to indicate you have processed it.

Here is an implenetation tip: if processing takes longer (d. h. if you need to wait for soundcard output or something like that), don't call processed immediately, but store the whole data packet and call processed only as soon as you really processed that packet. That way, senders have a chance to know how long it really takes to do your work.

As synchronization isn't so nice with asynchronous streams, you should use synchronous streams wherever possible, and asynchronous streams only when necessary.

Suppose you have 2 objects, for example an AudioProducer and an AudioConsumer. The AudioProducer has an output stream and AudioConsumer has an input one. Each time you want to connect them, you will use those 2 streams. The first use of defaulting is to enable you to make the connection without specifying the ports in that case.

Now suppose the teo objects above can handle stereo, and each have a „left“ and „right“ port. You'd still like to connect them as easily as before. But how can the connecting system know which output port to connect to which input port? It has no way to correctly map the streams. Defaulting is then used to specify several streams, with an order. Thus, when you connect an object with 2 default output streams to another one with 2 default input streams, you don't have to specify the ports, and the mapping will be done correctly.

Of course, this is not limited to stereo. Any number of streams can be made default if needed, and the connect function will check that the number of defaults for 2 object match (in the required direction) if you don't specify the ports to use.

The syntax is as follows: in the IDL, you can use the default keyword in the stream declaration, or on a single line. For example:

interface TwoToOneMixer {
    default in audio stream input1, input2;
    out audio stream output;
};

In this example, the object will expect its two input ports to be connected by default. The order is the one specified on the default line, so an object like this one:

interface DualNoiseGenerator {
    out audio stream bzzt, couic;
    default couic, bzzt;
};

Will make connections from „couic“ to „input1“, and „bzzt“ to „input2“ automatically. Note that since there is only one output for the mixer, it will be made default in this case (see below). The syntax used in the noise generator is useful to declare a different order than the declaration, or selecting only a few ports as default. The directions of the ports on this line will be looked up by mcopidl, so don't specify them. You can even mix input and output ports in such a line, only the order is important.

There are some rules that are followed when using inheritance:

When implementing objects that have attributes, you need to send change notifications whereever an attribute changes. The code for doing this looks like this:

 void KPoti_impl::value(float newValue)
 {
     if(newValue != _value)
     {
         _value = newValue;
         value_changed(newValue); // <- send change notification
     }
 }

It is strongly recommended to use code like this for all objects you implement, so that change notifications can be used by other people. You should however void sending notifications too often, so if you are doing signal processing, it is probably the best if you keep track when you sent your last notification, so that you don't send one with every sample you process.

It will be especially useful to use change notifications in conjunction with scopes (things that visualize audio data for instance), gui elements, control widgets, and monitoring. Code using this is in kdelibs/arts/tests, and in the experimental artsgui implementation, which you can find under kdemultimedia/arts/gui.

In MCOP there are no „in“ and „out“ parameters on method invocations. Parameters are always incoming, the return code is always outgoing, which means that the interface:

// CORBA idl
interface Account {
  void deposit( in long amount );
  void withdraw( in long amount );
  long balance();
};

is written as

// MCOP idl
interface Account {
  void deposit( long amount );
  void withdraw( long amount );
  long balance();
};

in MCOP.

There is no exception support. MCOP doesn't have exceptions - it uses something else for error handling.

There are no union types and no typedefs. I don't know if that is a real weakness, something one would desperately need to survive.

There is no support for passing interfaces or object references

You declare sequences as „sequencetype“ in MCOP. There is no need for a typedef. For example, instead of:

// CORBA idl
struct Line {
    long x1,y1,x2,y2;
};
typedef sequence<Line> LineSeq;
interface Plotter {
    void draw(in LineSeq lines);
};

you would write

// MCOP idl
struct Line {
    long x1,y1,x2,y2;
};
interface Plotter {
    void draw(sequence<Line> lines);
};

You can declare streams, which will then be evaluated by the aRts framework. Streams are declared in a similar manner to attributes. For example:

// MCOP idl
interface Synth_ADD : SynthModule {
    in audio stream signal1,signal2;
    out audio stream outvalue;
};

This says that your object will accept two incoming synchronous audio streams called signal1 and signal2. Synchronous means that these are streams that deliver x samples per second (or other time), so that the scheduler will guarantee to always provide you a balanced amount of input data (z. B. 200 samples of signal1 are there and 200 samples signal2 are there). You guarantee that if your object is called with those 200 samples signal1 + signal2, it is able to produce exactly 200 samples to outvalue.

This differs from CORBA mostly:

After having them passed through the IDL compiler, you need to derive from the _skel class. For instance, consider you have defined your interface like this:

// MCOP idl: hello.idl
interface Hello {
    void hello(string s);
    string concat(string s1, string s2);
    long sum2(long a, long b);
};

You pass that through the IDL compiler by calling mcopidl hello.idl, which will in turn generate hello.cc and hello.h. To implement it, you need to define a C++-class that inherits the skeleton:

// C++ header file - include hello.h somewhere
class Hello_impl : virtual public Hello_skel {
public:
    void hello(const string& s);
    string concat(const string& s1, const string& s2);
    long sum2(long a, long b);
};

Finally, you need to implement the methods as normal C++

// C++ implementation file

// as you see string's are passed as const string references
void Hello_impl::hello(const string& s)
{
    printf("Hello '%s'!\n",s.c_str());
}

// when they are a returncode they are passed as "normal" strings
string Hello_impl::concat(const string& s1, const string& s2)
{
    return s1+s2;
}

long Hello_impl::sum2(long a, long b)
{
    return a+b;
}

Once you do that, you have an object which can communicate using MCOP. Just create one (using the normal C++ facilities to create an object):

    Hello_impl server;

And as soon as you give somebody the reference

    string reference = server._toString();
    printf("%s\n",reference.c_str());

and go to the MCOP idle loop

Dispatcher::the()->run();

People can access the thing using

// this code can run anywhere - not necessarily in the same process
// (it may also run on a different computer/architecture)

    Hello *h = Hello::_fromString([the object reference printed above]);

and invoke methods:

    if(h)
        h->hello("test");
    else
        printf("Access failed?\n");

It has conceptual similarities to CORBA, but it is intended to extend it in all ways that are required for real time multimedia operations.

It provides a multimedia object model, which can be used for both: communication between components in one adress space (one process), and between components that are in different threads, processes or on different hosts.

All in all, it will be designed for extremely high performance (so everything shall be optimized to be blazingly fast), suitable for very communicative multimedia applications. For instance streaming videos around is one of the applications of MCOP, where most CORBA implementations would go down to their knees.

The interface definitions can handle the following natively:

and the most important CORBA gimmicks, like

Design goals/ideas:

Marshalling of the different types is show in the table below:

struct test {
    string name;        // which is "hello"
    long value;         // which is 10001025  (0x989a81)
};

If you need to refer to a type, all primitive types are referred by the names given above. Structures and enums get own names (like Header). Sequences are referred as *normal type, so that a sequence of longs is „*long“ and a sequence of Header struct's is „*Header“.

The MCOP message header format is defined as defined by this structure:

struct Header {
    long magic;          // the value 0x4d434f50, which is marshalled as MCOP
    long messageLength;
    long messageType;
};

The possible messageTypes are currently

 mcopServerHello		= 1
 mcopClientHello		= 2
 mcopAuthAccept			= 3
 mcopInvocation			= 4
 mcopReturn				= 5
 mcopOnewayInvocation   = 6

A few notes about the MCOP messaging:

The messageLength in the header is of course in some cases redundant, which means that this approach is not minimal regarding the number of bytes.

However, it leads to an easy (and fast) implementation of non-blocking messaging processing. With the help of the header, the messages can be received by protocol handling classes in the background (non-blocking), if there are many connections to the server, all of them can be served parallel. You don't need to look at the message content, to receive the message (and to determine when you are done), just at the header, so the code for that is pretty easy.

Once a message is there, it can be demarshalled and processed in one single pass, without caring about cases where not all data may have been received (because the messageLength guarantees that everything is there).

To call a remote method, you need to send the following structure in the body of an MCOP message with the messageType = 1 (mcopInvocation):

struct Invocation {
    long objectID;
    long methodID;
    long requestID;
};

after that, you send the parameters as structure, z. B. if you invoke the method string concat(string s1, string s2), you send a structure like

struct InvocationBody {
    string s1;
    string s2;
};

if the method was declared to be oneway - that means asynchronous without return code - then that was it. Otherwise, you'll receive as answer the message with messageType = 2 (mcopReturn)

struct ReturnCode {
    long requestID;
    <resulttype> result;
};

where <resulttype> is the type of the result. As void types are omitted in marshalling, you can also only write the requestID if you return from a void method.

So our string concat(string s1, string s2) would lead to a returncode like

struct ReturnCode {
    long   requestID;
    string result;
};

To do invocations, you need to know the methods an object supports. To do so, the methodID 0, 1, 2 and 3 are hardwired to certain functionalities. That is

long _lookupMethod(MethodDef methodDef);				// methodID always 0
string _interfaceName();								// methodID always 1
InterfaceDef _queryInterface(string name);				// methodID always 2
TypeDef _queryType(string name);						// methodID always 3

to read that, you of course need also

struct MethodDef {
	string  methodName;
	string  type;
	long    flags;        // set to 0 for now (will be required for streaming)
	sequence<ParamDef> signature;
};

struct ParamDef {
	string name;
	long   typeCode;
};

the parameters field contains type components which specify the types of the parameters. The type of the returncode is specified in the MethodDef's type field.

Strictly speaking, only the methods _lookupMethod() and _interfaceName() differ from object to object, while the _queryInterface() and _queryType() are always the same.

What are those methodIDs? If you do an MCOP invocation, you are expected to pass a number for the method you are calling. The reason for that is, that numbers can be processed much faster than strings when executing an MCOP request.

So how do you get those numbers? If you know the signature of the method, that is a MethodDef that describes the method, (which contains name, type, parameter names, parameter types and such), you can pass that to _lookupMethod of the object where you wish to call a method. As _lookupMethod is hardwired to methodID 0, you should encounter no problems doing so.

On the other hand, if you don't know the method signature, you can find which methods are supported by using _interfaceName, _queryInterface and _queryType.

User defined datatypes are described using the TypeDef structure:

struct TypeComponent {
	string type;
	string name;
};

struct TypeDef {
	string name;

	sequence<TypeComponent> contents;
};

The aRts C API 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 artsd), 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.

I did two ports as a proof of concept: mpg123 and quake. You can get the patches from here. 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.

Sending audio to the sound server with the API is very simple:

Here is a small example program that illustrates this:

#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;
}

To easily compile and link programs using the aRts C API, the artsc-config utility is provided which knows which libraries you need to link and where the includes are. It is called using

artsc-config  --libs

to find out the libraries and

artsc-config --cflags

to find out additional C compiler flags. The example above could have been compiled using the command line:

cc -o artsctest artsctest.c `artsc-config --cflags` `artsc-config --libs`

cc -o artsctest artsctest.c `artsc-config --cflags` `artsc-config --libs`

[TODO: generate the documentation for artsc.h using kdoc]