Bearbeiten von „RoarAudio/Programmieren/Intro“

Dies ist eine minimale Einleitung zur Programmierung mittels der [[RoarAudio]] Standard Bibliotheken.

Diese Anleitung setzt grundlegendes Verständnis zur Funktionsweise von RoarAudio voraus.

Dieses Dokument beschreibt die Standard API. Für sehr einfache Programme mag es angebracht sein die [[RoarAudio/Programmieren/Simple|Simple API]] oder die [[RoarAudio/Programmieren/VS|Very Simple API]] zu verwenden.

== Header Dateien ==
Um die RoarAudio API verwenden zu können müssen als erstes die richtigen Header eingebunden werden.
In aller Regel reicht es den Standard Header ein zu binden, welcher die meisten nötigen Header wiederum selbst einbindet:
 #include <roaraudio.h>

Zur Verwendung von libroardsp, libroarlight, libroarmidi und libroareio müssen weiterhin folgende Header entsprechend eingebunden werden:
 #include <libroardsp/libroardsp.h>
 #include <libroarlight/libroarlight.h>
 #include <libroarmidi/libroarmidi.h>
 #include <libroareio/libroareio.h>

Weiterhin gibt es noch einen speziellen Header zur Verwendung von Einheiten:
 #include <roaraudio/units.h>

== Verbindung zum Server ==
In aller Regel muss zu Beginn eine Verbindung zum Server aufgenommen werden. Dazu wird ein Objekt für die Verbindung angelegt und dies dann mit dem Server verbunden. Ist die Arbeit getan so wird die Verbindung wieder Beendet. Die Verbindung sollte aber offen gehalten werden sofern in absehbarer Zeit sonst eine neue Verbindung aufgebaut werden müsste. (Etwa sollte sie nicht bei einem Lied Wechsel in einem Player erst abgebaut und dann erneut Aufgebaut werden, sondern bestehen bleiben solange der Player nicht beendet wird durch den Benutzer).

Öffnen eines Steuerkanals:
 struct roar_connection con; // Steuer Verbindung
 
 if ( roar_simple_connect(&con, NULL, "Klient Name")) == -1 ) {
  return -1;
 }

In diesem Beispiel wird ein Objekt names ''con'' erzeugt und mit dem Standard Server (NULL) verbunden.
Wird anstatt ''NULL'' ein String übergeben so wird dieser als Server Name/Adresse verwendet. Das letzte Argument ist der Name des neuen Klienten. Dieser wird beispielsweise durch ''roarctl'' angezeigt.

Ist die Arbeit getan so kann die Verbindung einfach durch ''roar_disconnect()'' wieder geschlossen werden:

 roar_disconnect(&con);

== Erstellen eines Streams ==
Ist die Verbindung zum Server aufgebaut so wird in aller Regel eine Datenverbindung ''Stream'' aufgebaut. Der der Einfachkeit wegen werden in diesem Dokument nur Streams behandelt die direkt durch die Bibliothek verbunden werden.

Um einen Stream zu öffnen benötigt man nun zwei weitere Objekte: Das Stream Objekt welches die Informationen über den Stream selbst beinhaltet und das VIO Objekt welches uns die Möglichkeit bietet Daten mit dem Stream aus zu tauchen.

 struct roar_stream stream;  // Stream Objekt
 struct roar_vio_calls vio;  // VIO Objekt

Nachdem beide Objekte erstellt sind öffnen wir nun eine Daten Verbindung zum ''Abspielen von Waveform Daten''. Dies sind Streams zum abspielen von ''normaler'' Musik ([[PCM]] und PCM ähnliche Formate, kein [[MIDI]]).

 if ( roar_vio_simple_new_stream_obj(&vio,
                                     &con,
                                     &stream,
                                      rate, channels, bits,
                                      ROAR_CODEC_DEFAULT, ROAR_DIR_PLAY
                                    ) == -1 ) {
  return -1;
 }

Hierbei expandiert ROAR_CODEC_DEFAULT zu dem nativen PCM Format der aktuellen Maschine. ROAR_DIR_PLAY gibt an das wir Audio Daten abspielen möchten. rate, channels, bits sind entsprechend von der Applikation zu setzen entsprechend der aktuellen Daten. Übliche werte sind hier als Beispiel rate=44100Hz, channels=2, bits=16.

Sollen keine weiteren Informationen auf dem Stream gesetzt werden (Mixer Einstellungen, Meta Daten oder ähnliches) so kann das Stream Objekt ignoriert werden. Diese Einleitung tut dies, anderen Anleitungen mögen auf dieses Objekt detahierter eingehen.

Wollen wir nun Daten an den Server schicken so verwenden wir die VIO API. In unserem falle die Funktion ''roar_vio_write()'':

 ret = roar_vio_write(&vio, buffer, len);

Die Funktion erwartet einen Datenpuffer sowie dessen Größe. Sie liefert die Anzahl der geschriebenen Byte zurück. Siehe auch write(2).

Erreicht unsere Applikation das Ende der Daten (zum Beispiel das Dateiende der Quell-Datei) so schließen wir das VIO Objeckt mittels ''roar_vio_close()'':

 roar_vio_close(&vio);

Der Stream wird auf Seite des Servers beendet sobald dieser einen internen Puffer vollständig geleert hat. Dies kann je nach verwendetem Codec durchaus mehre Sekunden dauern. bei PCM Daten sollte dies allerdings im Milisekunden Bereich liegen und kann ignoriert werden.

Das Stream Objekt (''stream'') das wir oben angelegt haben verliert mit diesem Ereignis seine Gültigkeit. Aus diesem Grunde kann es ab dem Zeitpunkt zu dem wir das VIO Objekt geschlossen haben als ungültig angesehen werden.

== Themen Liste ==
=== libroar ===
; [[RoarAudio/Programmieren/Simple|Simple API]]
: API um simple Streams auf zu bauen.
; [[RoarAudio/Programmieren/Stream|Stream API]]
: API zur Steuerung von Streams.
; [[RoarAudio/Programmieren/Control|Control API]]
: API zur Steuerung des Servers.
; [[RoarAudio/Programmieren/VIO|Virtuelle IO (VIO)]]
: API für IO Handling.
; [[RoarAudio/Programmieren/VIO DSTR|VIO DSTR API]]
: API für das öffnen von VIO Objekten anhand von Beschreibende Strings (z.B. URLs)
; [[RoarAudio/Programmieren/VIO Typen|VIO Typen Liste]]
: Liste von möglichen VIO Typen.
; [[RoarAudio/Programmieren/Buffer|Memory Puffer]]
: API zur komfortablen Verwaltung von Memory Puffern.
; [[RoarAudio/Programmieren/MemMgr|Memory Management API]]
: API zur Memory Verwaltung.
; [[RoarAudio/Programmieren/roardl|RoarAudio Dynamic Library API]]
: API zum dynamischen Laden von Bibliotheken (z.B. Plugins)

=== libroardsp ===
; [[RoarAudio/Programmieren/Filter|Filter]]
: Verwenden von Signal Filtern.
; [[RoarAudio/Programmieren/Fader|Fader]]
: Überblend-Efeckte.
; [[RoarAudio/Programmieren/Transcode|Transcode]]
: Signal En-/De-/Transcoder.
; [[RoarAudio/Programmieren/Andere DSP Funktionen|Andere DSP Funktionen]]
: Andere Signalverarbeitungs Funktionen.

=== libroarlight ===
; [[RoarAudio/Programmieren/RoarDMX|RoarDMX]]
: RoarDMX Licht Steuerungs Codec

=== libroarmidi ===
; [[RoarAudio/Programmieren/MIDI|MIDI]]
: Umgang mit MIDI Signalen.

=== libroareio ===
; [[RoarAudio/Programmieren/CDriver|CDriver]]
: Klient seitige Treiber.

== Siehe Auch ==
* [[RoarAudio]]

== Weblinks ==
{{Homepage|roaraudio.keep-cool.org}}

[[Kategorie:RoarAudio]]
[[Kategorie:Software]]
[[Kategorie:Sound]]
[[Kategorie:Programmierung]]
{{Stub}}